@agentikos/omega-os 0.19.52 → 0.19.54

package/bootstrap/lib/common.sh

@@ -676,6 +676,30 @@ except Exception: print("unknown")' 2>/dev/null)" || readiness="unknown"
   printf '   %s   %sissues%s  %sgithub.com/agentik-os/OmegaOS/issues%s\n' "$bar" "$C_BOLD" "$C_RST" "$C_DIM" "$C_RST"
   printf '   %s\n' "$bot"
 
+  # ── Terminal config tips for Option+key shortcuts ────────────────────
+  # tmux binds M-z / M-/ for the Omega popup menu + session switcher.
+  # macOS Terminal.app + Termius default send the literal Unicode
+  # character on Option+key (Ω, ÷) instead of the Esc+key (Meta) sequence
+  # tmux expects. The Unicode fallback binds in tmux.py cover that, but
+  # configuring the terminal once gives the user a proper Meta key.
+  log ""
+  log "${C_ORANGE}━ Terminal config required for Option+key shortcuts ━${C_RST}"
+  log ""
+  log "  ${C_BOLD}Option+Z${C_RST}   → Omega menu (popup)"
+  log "  ${C_BOLD}Option+/${C_RST}   → Session switcher (popup)"
+  log "  ${C_BOLD}Option+O${C_RST}   → Omega menu (alternate, when tmux-claude is preserved)"
+  log ""
+  log "  For these to fire, your terminal must send Option as Esc+ (Meta):"
+  log ""
+  log "  ${C_BOLD}iTerm2${C_RST}     Settings → Profiles → Keys → Left Option Key: ${C_BOLD}Esc+${C_RST}"
+  log "  ${C_BOLD}Terminal.app${C_RST}  Settings → Profile → Keyboard → ☑ ${C_BOLD}Use Option as Meta key${C_RST}"
+  log "  ${C_BOLD}Termius${C_RST}    Settings → Terminal → Option key → ${C_BOLD}Send Esc${C_RST}"
+  log "  ${C_BOLD}Warp${C_RST}       Settings → Input → ☑ ${C_BOLD}Option as Meta${C_RST}"
+  log "  ${C_BOLD}Alacritty${C_RST}  add to alacritty.toml: ${C_DIM}[env]\\nALACRITTY_OPTION_AS_ALT = \"Both\"${C_RST}"
+  log ""
+  log "  Without this, Option+Z sends ${C_DIM}Ω${C_RST} (Unicode) instead of ${C_DIM}\\e z${C_RST} — tmux never sees the bind."
+  log ""
+
   # If PARTIAL or NOT READY, tell them where to look.
   case "$verdict_text" in
     PARTIAL|"NOT READY")

package/bootstrap/lib/steps.sh

@@ -427,6 +427,15 @@ step_claude_code_settings() {
 }
 
 step_engine() {
+  # v0.19.54 — neutralize broken claude-mem here too, NOT just in
+  # step_claude_plugins. The plugins step can be skipped/idempotent on
+  # re-install, but step_engine ALWAYS re-runs on version drift (it's
+  # in the force-rerun list). This guarantees the broken plugin is
+  # disabled on every upgrade, even if step 45 is somehow skipped.
+  if declare -f _disable_broken_claude_plugins >/dev/null 2>&1; then
+    _disable_broken_claude_plugins
+  fi
+
   local uv_bin; uv_bin="$(command -v uv || echo "$HOME/.local/bin/uv")"
   [ -x "$uv_bin" ] || { err "uv not found after step 10"; return 1; }
   cd "$OMEGA_HOME/Agentik_Engine" || { err "engine block missing"; return 1; }

package/omega/Agentik_Engine/omega_engine/__init__.py

@@ -3,192 +3,256 @@
 Event-sourced, verified-completion agent graphs. The engine is business-agnostic:
 it executes graphs of Tasks. Who is an "oracle" and which topology runs lives in
 Agentik_Orchestration/, never here.
+
+v0.19.53 — PEP 562 lazy attribute loading. Previously, importing
+``omega_engine`` (or any submodule like ``omega_engine.cli``) eagerly pulled
+the full submodule tree — ``account``, ``autonomous``, ``audit``, ``educators``,
+``rag``, ``skill_discovery``, ``genesis``, ``provider``, ``executor`` and 40+
+others — at module-load time. On macOS uv-Python that's ~500-1500ms of import
+cost paid before *any* CLI argument is parsed, which made bare ``omega``
+(menu) feel sluggish even after v0.19.50 removed runtime tmux probes.
+
+Each public re-export is now declared in ``_LAZY_MAP``: a mapping from the
+public name to ``(submodule_path, attribute_name)``. ``__getattr__`` (PEP
+562) resolves the import on first access, so ``from omega_engine import
+WorkerBrief`` still works, but ``import omega_engine`` itself touches *zero*
+heavy submodules.
+
+Submodules (``omega_engine.tmux``, ``omega_engine.cli``, etc.) are still
+auto-importable by Python's standard submodule mechanism — they don't need
+to be in ``_LAZY_MAP``.
 """
-from omega_engine.account import (
-    AccountPool,
-    BillingAggregator,
-    ClaudeAccount,
-)
-from omega_engine.audit import AuditFinding, AuditGate, AuditVerdict
-from omega_engine.audit_arsenal import (
-    ArsenalGate,
-    ArsenalVerdict,
-    Audit,
-    AuditRegistry,
-    run_forensic_audit,
-)
-from omega_engine.autonomous import (
-    AutonomousSupervisor,
-    Charter,
-    build_supervisor_from_home,
-    load_charters,
-    next_fire,
-    parse_cron,
-)
-from omega_engine.barrier import ScopeStatus, scope_status
-from omega_engine.educators import (
-    Artifact,
-    ArtifactEducator,
-    AutomationEducator,
-    ClaudecodeEducator,
-    ConnectionEducator,
-    CoworkerEducator,
-    Educator,
-    EducatorProposal,
-    EducatorRegistry,
-    LoopEducator,
-    PromptEducator,
-    SkillEducator,
-    StagingPipeline,
-    StagingRecord,
-)
-from omega_engine.bus import EventBus
-from omega_engine.events import Event, EventType
-from omega_engine.executor import Executor, MissionResult
-from omega_engine.integrations import (
-    GraphifyError,
-    GraphifyGraphMissing,
-    GraphifyNotInstalled,
-    GraphifyReport,
-    graphify_install_skill,
-    graphify_into_rag,
-    graphify_load_graph,
-    graphify_version,
-    is_graphify_installed,
-)
-from omega_engine.progress import MissionProgress, ProgressTracker
-from omega_engine.provider import (
-    AgentProvider,
-    AgentRequest,
-    AgentResult,
-    ClaudeProvider,
-    DeepSeekProvider,
-    GLMProvider,
-    MockProvider,
-    OpenAIProvider,
-)
-from omega_engine.rag import (
-    AgenticRetriever,
-    CorrectiveRetriever,
-    Document,
-    GraphRetriever,
-    HybridRetriever,
-    MultimodalRetriever,
-    RAGRouter,
-    RetrievalResult,
-    Retriever,
-)
-from omega_engine.reducer import IllegalTransition, reduce, reduce_task
-from omega_engine.router import ModelRouter
-from omega_engine.store import EventStore, SQLiteStore
-from omega_engine.cadence import (
-    CadenceCharter,
-    disable_cadence,
-    list_cadences,
-    remove_cadence,
-    schedule_cadence,
-)
-from omega_engine.pursue import PursueResult, pursue
-from omega_engine.webhooks import (
-    WebhookRegistry,
-    WebhookSpec,
-    generate_test_signature,
-    handle_webhook,
-    load_registry as load_webhook_registry,
-    signature_header_for,
-    verify_signature,
-)
-from omega_engine.skill_discovery import (
-    DiscoveredSkill,
-    Marketplace,
-    SkillAuditIssue,
-    SkillAuditVerdict,
-    SkillInstallResult,
-    audit_skill_file,
-    audit_skill_text,
-    discover_skills,
-    install_skill_from_github,
-    list_curated,
-    load_marketplaces,
-)
-from omega_engine.sync import ClaudeCodeAdapter, SyncEngine
-from omega_engine.done_signal import (
-    DoneSignal,
-    DoneSignalError,
-    attach_audit_to_done,
-    done_path,
-    read_done,
-    session_dir,
-    write_done,
-)
-from omega_engine.envelope import (
-    DISPATCHER_ROLES,
-    EXECUTOR_ROLES,
-    EnvelopeContext,
-    VERIFIER_ROLES,
-    build_envelope,
-)
-from omega_engine.prompts import (
-    find_agent_file,
-    list_available_agents,
-    load_agent_prompt,
-)
-from omega_engine.vault import (
-    list_project_vaults,
-    vault_init,
-    vault_read,
-    vault_status,
-    vault_write,
-)
-from omega_engine.task import (
-    TERMINAL,
-    Budget,
-    Kind,
-    Lifecycle,
-    Task,
-    TaskState,
-    Trigger,
-)
-from omega_engine.tools import Tool, ToolRegistry, install_from_catalog
-from omega_engine.worker import (
-    WorkerBrief,
-    default_model_for_role,
-    list_workers,
-    read_brief,
-    run_brief,
-    spawn_worker,
-    wait_for_done,
-    worker_status,
-    write_brief,
-)
-from omega_engine.cleanup import (
-    TierResult,
-    cleanup as run_cleanup,
-    format_summary as cleanup_summary,
-)
-from omega_engine.skill_routing import (
-    POWER_SKILLS,
-    catalog_for_home as skill_catalog_for_home,
-    format_skill_block,
-    recommend as recommend_skills,
-    skills_for,
-)
-from omega_engine.genesis import (
-    GenesisOrchestrator,
-    GenesisState,
-    PhaseResult,
-    Stack,
-    StackConfig,
-    StackQuestion,
-    init_project as genesis_init_project,
-    load_state as genesis_load_state,
-    pick_stack,
-    project_root as genesis_project_root,
-    stack_questions,
-)
-from omega_engine import plan as plan_v7
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+__version__ = "0.19.54"
+
+# Public-name → (module_path, attribute_name) map.
+# ``attribute_name = None`` means "return the whole module" (used for the
+# ``plan_v7`` alias that points at the ``omega_engine.plan`` submodule).
+_LAZY_MAP: dict[str, tuple[str, str | None]] = {
+    # account pool + billing
+    "AccountPool":                  ("omega_engine.account", "AccountPool"),
+    "BillingAggregator":            ("omega_engine.account", "BillingAggregator"),
+    "ClaudeAccount":                ("omega_engine.account", "ClaudeAccount"),
+    # audit (the canonical AuditGate / AuditVerdict / AuditFinding)
+    "AuditFinding":                 ("omega_engine.audit", "AuditFinding"),
+    "AuditGate":                    ("omega_engine.audit", "AuditGate"),
+    "AuditVerdict":                 ("omega_engine.audit", "AuditVerdict"),
+    # audit_arsenal — multi-audit forensic harness
+    "ArsenalGate":                  ("omega_engine.audit_arsenal", "ArsenalGate"),
+    "ArsenalVerdict":               ("omega_engine.audit_arsenal", "ArsenalVerdict"),
+    "Audit":                        ("omega_engine.audit_arsenal", "Audit"),
+    "AuditRegistry":                ("omega_engine.audit_arsenal", "AuditRegistry"),
+    "run_forensic_audit":           ("omega_engine.audit_arsenal", "run_forensic_audit"),
+    # autonomous-agent supervisor + charters
+    "AutonomousSupervisor":         ("omega_engine.autonomous", "AutonomousSupervisor"),
+    "Charter":                      ("omega_engine.autonomous", "Charter"),
+    "build_supervisor_from_home":   ("omega_engine.autonomous", "build_supervisor_from_home"),
+    "load_charters":                ("omega_engine.autonomous", "load_charters"),
+    "next_fire":                    ("omega_engine.autonomous", "next_fire"),
+    "parse_cron":                   ("omega_engine.autonomous", "parse_cron"),
+    # barrier
+    "ScopeStatus":                  ("omega_engine.barrier", "ScopeStatus"),
+    "scope_status":                 ("omega_engine.barrier", "scope_status"),
+    # educators — the self-improving layer
+    "Artifact":                     ("omega_engine.educators", "Artifact"),
+    "ArtifactEducator":             ("omega_engine.educators", "ArtifactEducator"),
+    "AutomationEducator":           ("omega_engine.educators", "AutomationEducator"),
+    "ClaudecodeEducator":           ("omega_engine.educators", "ClaudecodeEducator"),
+    "ConnectionEducator":           ("omega_engine.educators", "ConnectionEducator"),
+    "CoworkerEducator":             ("omega_engine.educators", "CoworkerEducator"),
+    "Educator":                     ("omega_engine.educators", "Educator"),
+    "EducatorProposal":             ("omega_engine.educators", "EducatorProposal"),
+    "EducatorRegistry":             ("omega_engine.educators", "EducatorRegistry"),
+    "LoopEducator":                 ("omega_engine.educators", "LoopEducator"),
+    "PromptEducator":               ("omega_engine.educators", "PromptEducator"),
+    "SkillEducator":                ("omega_engine.educators", "SkillEducator"),
+    "StagingPipeline":              ("omega_engine.educators", "StagingPipeline"),
+    "StagingRecord":                ("omega_engine.educators", "StagingRecord"),
+    # bus
+    "EventBus":                     ("omega_engine.bus", "EventBus"),
+    # events
+    "Event":                        ("omega_engine.events", "Event"),
+    "EventType":                    ("omega_engine.events", "EventType"),
+    # executor
+    "Executor":                     ("omega_engine.executor", "Executor"),
+    "MissionResult":                ("omega_engine.executor", "MissionResult"),
+    # integrations — graphify
+    "GraphifyError":                ("omega_engine.integrations", "GraphifyError"),
+    "GraphifyGraphMissing":         ("omega_engine.integrations", "GraphifyGraphMissing"),
+    "GraphifyNotInstalled":         ("omega_engine.integrations", "GraphifyNotInstalled"),
+    "GraphifyReport":               ("omega_engine.integrations", "GraphifyReport"),
+    "graphify_install_skill":       ("omega_engine.integrations", "graphify_install_skill"),
+    "graphify_into_rag":            ("omega_engine.integrations", "graphify_into_rag"),
+    "graphify_load_graph":          ("omega_engine.integrations", "graphify_load_graph"),
+    "graphify_version":             ("omega_engine.integrations", "graphify_version"),
+    "is_graphify_installed":        ("omega_engine.integrations", "is_graphify_installed"),
+    # progress
+    "MissionProgress":              ("omega_engine.progress", "MissionProgress"),
+    "ProgressTracker":              ("omega_engine.progress", "ProgressTracker"),
+    # provider
+    "AgentProvider":                ("omega_engine.provider", "AgentProvider"),
+    "AgentRequest":                 ("omega_engine.provider", "AgentRequest"),
+    "AgentResult":                  ("omega_engine.provider", "AgentResult"),
+    "ClaudeProvider":               ("omega_engine.provider", "ClaudeProvider"),
+    "DeepSeekProvider":             ("omega_engine.provider", "DeepSeekProvider"),
+    "GLMProvider":                  ("omega_engine.provider", "GLMProvider"),
+    "MockProvider":                 ("omega_engine.provider", "MockProvider"),
+    "OpenAIProvider":               ("omega_engine.provider", "OpenAIProvider"),
+    # rag
+    "AgenticRetriever":             ("omega_engine.rag", "AgenticRetriever"),
+    "CorrectiveRetriever":          ("omega_engine.rag", "CorrectiveRetriever"),
+    "Document":                     ("omega_engine.rag", "Document"),
+    "GraphRetriever":               ("omega_engine.rag", "GraphRetriever"),
+    "HybridRetriever":              ("omega_engine.rag", "HybridRetriever"),
+    "MultimodalRetriever":          ("omega_engine.rag", "MultimodalRetriever"),
+    "RAGRouter":                    ("omega_engine.rag", "RAGRouter"),
+    "RetrievalResult":              ("omega_engine.rag", "RetrievalResult"),
+    "Retriever":                    ("omega_engine.rag", "Retriever"),
+    # reducer
+    "IllegalTransition":            ("omega_engine.reducer", "IllegalTransition"),
+    "reduce":                       ("omega_engine.reducer", "reduce"),
+    "reduce_task":                  ("omega_engine.reducer", "reduce_task"),
+    # router
+    "ModelRouter":                  ("omega_engine.router", "ModelRouter"),
+    # store
+    "EventStore":                   ("omega_engine.store", "EventStore"),
+    "SQLiteStore":                  ("omega_engine.store", "SQLiteStore"),
+    # cadence
+    "CadenceCharter":               ("omega_engine.cadence", "CadenceCharter"),
+    "disable_cadence":              ("omega_engine.cadence", "disable_cadence"),
+    "list_cadences":                ("omega_engine.cadence", "list_cadences"),
+    "remove_cadence":               ("omega_engine.cadence", "remove_cadence"),
+    "schedule_cadence":             ("omega_engine.cadence", "schedule_cadence"),
+    # pursue
+    "PursueResult":                 ("omega_engine.pursue", "PursueResult"),
+    "pursue":                       ("omega_engine.pursue", "pursue"),
+    # webhooks
+    "WebhookRegistry":              ("omega_engine.webhooks", "WebhookRegistry"),
+    "WebhookSpec":                  ("omega_engine.webhooks", "WebhookSpec"),
+    "generate_test_signature":      ("omega_engine.webhooks", "generate_test_signature"),
+    "handle_webhook":               ("omega_engine.webhooks", "handle_webhook"),
+    "load_webhook_registry":        ("omega_engine.webhooks", "load_registry"),
+    "signature_header_for":         ("omega_engine.webhooks", "signature_header_for"),
+    "verify_signature":             ("omega_engine.webhooks", "verify_signature"),
+    # skill_discovery
+    "DiscoveredSkill":              ("omega_engine.skill_discovery", "DiscoveredSkill"),
+    "Marketplace":                  ("omega_engine.skill_discovery", "Marketplace"),
+    "SkillAuditIssue":              ("omega_engine.skill_discovery", "SkillAuditIssue"),
+    "SkillAuditVerdict":            ("omega_engine.skill_discovery", "SkillAuditVerdict"),
+    "SkillInstallResult":           ("omega_engine.skill_discovery", "SkillInstallResult"),
+    "audit_skill_file":             ("omega_engine.skill_discovery", "audit_skill_file"),
+    "audit_skill_text":             ("omega_engine.skill_discovery", "audit_skill_text"),
+    "discover_skills":              ("omega_engine.skill_discovery", "discover_skills"),
+    "install_skill_from_github":    ("omega_engine.skill_discovery", "install_skill_from_github"),
+    "list_curated":                 ("omega_engine.skill_discovery", "list_curated"),
+    "load_marketplaces":            ("omega_engine.skill_discovery", "load_marketplaces"),
+    # sync
+    "ClaudeCodeAdapter":            ("omega_engine.sync", "ClaudeCodeAdapter"),
+    "SyncEngine":                   ("omega_engine.sync", "SyncEngine"),
+    # done_signal
+    "DoneSignal":                   ("omega_engine.done_signal", "DoneSignal"),
+    "DoneSignalError":              ("omega_engine.done_signal", "DoneSignalError"),
+    "attach_audit_to_done":         ("omega_engine.done_signal", "attach_audit_to_done"),
+    "done_path":                    ("omega_engine.done_signal", "done_path"),
+    "read_done":                    ("omega_engine.done_signal", "read_done"),
+    "session_dir":                  ("omega_engine.done_signal", "session_dir"),
+    "write_done":                   ("omega_engine.done_signal", "write_done"),
+    # envelope
+    "DISPATCHER_ROLES":             ("omega_engine.envelope", "DISPATCHER_ROLES"),
+    "EXECUTOR_ROLES":               ("omega_engine.envelope", "EXECUTOR_ROLES"),
+    "EnvelopeContext":              ("omega_engine.envelope", "EnvelopeContext"),
+    "VERIFIER_ROLES":               ("omega_engine.envelope", "VERIFIER_ROLES"),
+    "build_envelope":               ("omega_engine.envelope", "build_envelope"),
+    # prompts
+    "find_agent_file":              ("omega_engine.prompts", "find_agent_file"),
+    "list_available_agents":        ("omega_engine.prompts", "list_available_agents"),
+    "load_agent_prompt":            ("omega_engine.prompts", "load_agent_prompt"),
+    # vault
+    "list_project_vaults":          ("omega_engine.vault", "list_project_vaults"),
+    "vault_init":                   ("omega_engine.vault", "vault_init"),
+    "vault_read":                   ("omega_engine.vault", "vault_read"),
+    "vault_status":                 ("omega_engine.vault", "vault_status"),
+    "vault_write":                  ("omega_engine.vault", "vault_write"),
+    # task model + FSM
+    "TERMINAL":                     ("omega_engine.task", "TERMINAL"),
+    "Budget":                       ("omega_engine.task", "Budget"),
+    "Kind":                         ("omega_engine.task", "Kind"),
+    "Lifecycle":                    ("omega_engine.task", "Lifecycle"),
+    "Task":                         ("omega_engine.task", "Task"),
+    "TaskState":                    ("omega_engine.task", "TaskState"),
+    "Trigger":                      ("omega_engine.task", "Trigger"),
+    # tools
+    "Tool":                         ("omega_engine.tools", "Tool"),
+    "ToolRegistry":                 ("omega_engine.tools", "ToolRegistry"),
+    "install_from_catalog":         ("omega_engine.tools", "install_from_catalog"),
+    # worker — persistent tmux worker briefs
+    "WorkerBrief":                  ("omega_engine.worker", "WorkerBrief"),
+    "default_model_for_role":       ("omega_engine.worker", "default_model_for_role"),
+    "list_workers":                 ("omega_engine.worker", "list_workers"),
+    "read_brief":                   ("omega_engine.worker", "read_brief"),
+    "run_brief":                    ("omega_engine.worker", "run_brief"),
+    "spawn_worker":                 ("omega_engine.worker", "spawn_worker"),
+    "wait_for_done":                ("omega_engine.worker", "wait_for_done"),
+    "worker_status":                ("omega_engine.worker", "worker_status"),
+    "write_brief":                  ("omega_engine.worker", "write_brief"),
+    # cleanup
+    "TierResult":                   ("omega_engine.cleanup", "TierResult"),
+    "run_cleanup":                  ("omega_engine.cleanup", "cleanup"),
+    "cleanup_summary":              ("omega_engine.cleanup", "format_summary"),
+    # skill_routing
+    "POWER_SKILLS":                 ("omega_engine.skill_routing", "POWER_SKILLS"),
+    "skill_catalog_for_home":       ("omega_engine.skill_routing", "catalog_for_home"),
+    "format_skill_block":           ("omega_engine.skill_routing", "format_skill_block"),
+    "recommend_skills":             ("omega_engine.skill_routing", "recommend"),
+    "skills_for":                   ("omega_engine.skill_routing", "skills_for"),
+    # genesis
+    "GenesisOrchestrator":          ("omega_engine.genesis", "GenesisOrchestrator"),
+    "GenesisState":                 ("omega_engine.genesis", "GenesisState"),
+    "PhaseResult":                  ("omega_engine.genesis", "PhaseResult"),
+    "Stack":                        ("omega_engine.genesis", "Stack"),
+    "StackConfig":                  ("omega_engine.genesis", "StackConfig"),
+    "StackQuestion":                ("omega_engine.genesis", "StackQuestion"),
+    "genesis_init_project":         ("omega_engine.genesis", "init_project"),
+    "genesis_load_state":           ("omega_engine.genesis", "load_state"),
+    "pick_stack":                   ("omega_engine.genesis", "pick_stack"),
+    "genesis_project_root":         ("omega_engine.genesis", "project_root"),
+    "stack_questions":              ("omega_engine.genesis", "stack_questions"),
+    # plan submodule re-export (was: `from omega_engine import plan as plan_v7`)
+    "plan_v7":                      ("omega_engine.plan", None),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 lazy attribute loader.
+
+    Resolves the import on first access, caches the value on this module so
+    subsequent lookups bypass __getattr__. Submodules (``omega_engine.tmux``
+    etc.) are NOT in _LAZY_MAP; Python's standard submodule import handles
+    those automatically when they're referenced as ``omega_engine.<name>`` or
+    ``from omega_engine import <submodule>``.
+    """
+    entry = _LAZY_MAP.get(name)
+    if entry is None:
+        raise AttributeError(
+            f"module 'omega_engine' has no attribute {name!r}"
+        )
+    mod_path, attr = entry
+    module = importlib.import_module(mod_path)
+    value = module if attr is None else getattr(module, attr)
+    # Cache so subsequent lookups are direct dict reads.
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Make tab-completion and introspection show all public names without
+    triggering a load."""
+    return sorted(list(globals().keys()) + list(_LAZY_MAP.keys()))
 
-__version__ = "0.19.52"
 
 __all__ = [
     "__version__",

package/omega/Agentik_Engine/omega_engine/cli.py

@@ -2949,11 +2949,28 @@ def _attach_or_spawn_chat(session_name: str, *,
             print(f"  could not spawn {label}: {exc}")
             print(f"  try manually: tmux new -d -s {session_name}")
             return 2
-    # Inside tmux already? Tell the user to switch (we can't from here).
+    # Inside tmux already? Do the switch ourselves — v0.19.54 fix.
+    # Previously we PRINTED instructions ("Switch with: tmux switch-client
+    # -t Omega:hermes") and exited, leaving the user staring at a useless
+    # hint. Same bug pattern as cmd_menu had in v0.19.40 (fixed v0.19.41).
+    # tmux switch-client works fine from inside a tmux client and is
+    # exactly what the user wants.
     if os.environ.get("TMUX"):
-        print(f"  already inside tmux — switch with:")
-        print(f"    tmux switch-client -t {session_name}")
-        print(f"  or detach (Ctrl-b d) then `omega` again.")
+        import subprocess as _sp
+        # Window of Omega session, or standalone session — try
+        # select-window first (for Omega:<name>), then switch-client.
+        if ":" in session_name:
+            sess, win = session_name.split(":", 1)
+            rc = _sp.run(["tmux", "select-window", "-t", session_name],
+                         capture_output=True).returncode
+            if rc != 0:
+                _sp.run(["tmux", "switch-client", "-t", sess],
+                        capture_output=True)
+                _sp.run(["tmux", "select-window", "-t", session_name],
+                        capture_output=True)
+        else:
+            _sp.run(["tmux", "switch-client", "-t", session_name],
+                    capture_output=True)
         return 0
     # Outside tmux — replace this process with `tmux attach`.
     print(f"  attaching to {label} ({session_name})…")
@@ -3577,9 +3594,21 @@ def cmd_hermes(args: argparse.Namespace) -> int:
     if sub == "chat-loop":
         # REPL that runs inside the Hermes-chat tmux session.
         # Uses Anthropic API directly (separate from AISB's Max OAuth).
+        #
+        # v0.19.53 — DO NOT `import os, sys` here. Both are already
+        # imported at module scope (lines 11–12). Re-importing them
+        # inside this branch made Python treat `sys` and `os` as
+        # local-to-`cmd_hermes` for the WHOLE function — so the
+        # `ask` / `env` / `brief observe` / help-fallback branches
+        # then crashed with `UnboundLocalError: cannot access local
+        # variable 'sys'` when their try/except caught a HermesError
+        # and tried `print(..., file=sys.stderr)`. End result for a
+        # fresh Mac install: `omega hermes ask hi` printed a raw
+        # traceback instead of `error: \`hermes\` not on PATH — run
+        # \`omega hermes install\``. The user reported "hermes doesn't
+        # work" because of this misleading crash.
         from omega_engine.aisb_chat import chat_once
         from omega_engine.vault import vault_read
-        import os, sys
         home = _omega_home()
         api_key = (vault_read(home, "ANTHROPIC_API_KEY_HERMES") or "").strip()
         if not api_key:

package/omega/Agentik_Engine/omega_engine/provider_state.py

@@ -20,7 +20,13 @@ DEFAULT_PROVIDER = "claude_code"
 
 
 def _omega_home() -> Path:
-    return Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+    # v0.19.53 — avoid Path.home() on Mac uv-Python (slow: 200-500ms
+    # via pwd.getpwuid() + DirectoryService lookup). Use $HOME env
+    # directly via os.path.expanduser — milliseconds.
+    omega = os.environ.get("OMEGA_HOME")
+    if omega:
+        return Path(omega)
+    return Path(os.path.expanduser("~/Omega"))
 
 
 def provider_state_path() -> Path:

package/omega/Agentik_Engine/omega_engine/tmux.py

@@ -631,6 +631,13 @@ bind-key S choose-tree -Zs
 bind-key -n M-/ display-popup -E -w 100% -h 100% "__OMEGA_BIN__ tmux switcher"
 bind-key -n M-z display-popup -E -w 100% -h 100% "__OMEGA_BIN__ menu-tui"
 
+# Fallback for terminals that don't send Esc+ on Option+key (e.g. macOS
+# Terminal.app without "Option as Meta", Termius default). These bind
+# the LITERAL Unicode character that Option+Z / Option+/ produces.
+# Safe — these characters are extremely rarely typed intentionally.
+bind-key -n "Ω" display-popup -E -w 100% -h 100% "__OMEGA_BIN__ menu-tui"
+bind-key -n "÷" display-popup -E -w 100% -h 100% "__OMEGA_BIN__ tmux switcher"
+
 # ════════════════════════════════════════════════════════════════════
 # Pixel/CRT amber theme (tmux-claude inspired)
 # xterm colour137 ≈ #af8700 — amber/gold on whatever your terminal bg is.
@@ -768,6 +775,13 @@ bind-key r source-file ~/.tmux.conf \\; display-message "tmux.conf reloaded"
 bind-key -n M-/ display-popup -E -w 100% -h 100% "__OMEGA_BIN__ tmux switcher"
 bind-key -n M-z display-popup -E -w 100% -h 100% "__OMEGA_BIN__ menu-tui"
 
+# Fallback for terminals that don't send Esc+ on Option+key (e.g. macOS
+# Terminal.app without "Option as Meta", Termius default). These bind
+# the LITERAL Unicode character that Option+Z / Option+/ produces.
+# Safe — these characters are extremely rarely typed intentionally.
+bind-key -n "Ω" display-popup -E -w 100% -h 100% "__OMEGA_BIN__ menu-tui"
+bind-key -n "÷" display-popup -E -w 100% -h 100% "__OMEGA_BIN__ tmux switcher"
+
 # ════════════════════════════════════════════════════════════════════
 # Pixel/CRT amber theme (tmux-claude inspired)
 # ════════════════════════════════════════════════════════════════════

package/omega/Agentik_Engine/omega_engine/tui.py

@@ -48,16 +48,26 @@ import shlex
 from pathlib import Path
 from typing import Any
 
-try:
-    from textual.app import App, ComposeResult
-    from textual.widgets import (
-        Header, Footer, Input, RichLog, ListView, ListItem, Label,
-    )
-    from textual.containers import Horizontal, Vertical
-    from textual.binding import Binding
-    TEXTUAL_AVAILABLE = True
-except ImportError:
-    TEXTUAL_AVAILABLE = False
+# v0.19.53 — defer the textual import to runtime. Importing
+# ``textual.app`` triggers ~80-150ms of import cost on macOS uv-Python (60+
+# transitive modules: rich, markupsafe, jinja-ish, etc.). The default
+# ``omega`` UX is the fzf arrow-key menu (``_arrow_menu``), which does NOT
+# need textual at all. We only need it when the user explicitly opts in
+# with ``--textual``. So we probe lazily and build the class on demand.
+TEXTUAL_AVAILABLE: bool | None = None  # tri-state: None = not probed yet
+
+
+def _probe_textual() -> bool:
+    """Return True iff the ``textual`` package is importable. Caches the
+    answer so the probe only runs once per process."""
+    global TEXTUAL_AVAILABLE
+    if TEXTUAL_AVAILABLE is None:
+        try:
+            import importlib.util as _util
+            TEXTUAL_AVAILABLE = _util.find_spec("textual") is not None
+        except Exception:  # noqa: BLE001
+            TEXTUAL_AVAILABLE = False
+    return TEXTUAL_AVAILABLE
 
 
 # ---------------------------------------------------------------------------
@@ -256,7 +266,29 @@ def dispatch_slash(line: str) -> CommandResult:
 # ---------------------------------------------------------------------------
 
 
-if TEXTUAL_AVAILABLE:
+def _build_omega_tui_class():
+    """Build the ``OmegaTUI`` class on first request.
+
+    v0.19.53 — previously the class lived at module level inside
+    ``if TEXTUAL_AVAILABLE: class OmegaTUI(App): ...``, which forced
+    ``textual.app`` (+ 60 transitive modules including ``rich``) to load
+    every time ``omega_engine.tui`` was imported — even for the default
+    fzf arrow-key menu that never touches textual.
+
+    Building the class on demand keeps the default ``omega`` startup path
+    free of the textual import cost. The class is cached on a function
+    attribute so subsequent calls return the same class.
+    """
+    cached = getattr(_build_omega_tui_class, "_cls", None)
+    if cached is not None:
+        return cached
+
+    from textual.app import App, ComposeResult
+    from textual.widgets import (
+        Header, Footer, Input, RichLog, ListView, ListItem, Label,
+    )
+    from textual.containers import Horizontal, Vertical
+    from textual.binding import Binding
 
     class OmegaTUI(App):
         """OmegaOS Textual TUI — the v0.19.27 control surface."""
@@ -409,6 +441,9 @@ if TEXTUAL_AVAILABLE:
             if res.session_jump:
                 _switch_client(res.session_jump)
 
+    _build_omega_tui_class._cls = OmegaTUI  # type: ignore[attr-defined]
+    return OmegaTUI
+
 
 def _arrow_menu() -> int:
     """v0.19.30 — fzf-driven arrow-key menu (the default `omega` UX).
@@ -962,8 +997,9 @@ def run_tui(prefer_textual: bool = False,
       - `--repl`      → `_plain_repl()` (input() loop, slash commands)
       - `--textual`   → Textual TUI (opt-in, may break under tmux)
     """
-    if prefer_textual and TEXTUAL_AVAILABLE:
+    if prefer_textual and _probe_textual():
         try:
+            OmegaTUI = _build_omega_tui_class()
             app = OmegaTUI()
             app.run()
             return 0

package/omega/Agentik_Engine/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omega-engine"
-version = "0.19.52"
+version = "0.19.54"
 description = "The Omega OS orchestration engine — event-sourced, verified-completion agent graphs."
 readme = "README.md"
 requires-python = ">=3.11"

package/omega/Agentik_Engine/tests/test_tmux_palette.py

@@ -247,6 +247,19 @@ class TestTmuxBindsFixedAndPathsAbsolute(unittest.TestCase):
         self.assertIn('"Omega:hermes"', src,
             "spawn_hermes_chat must return 'Omega:hermes'")
 
+    def test_unicode_fallback_binds_for_macos_terminal(self):
+        """v0.19.53 — Option+Z / Option+/ on macOS Terminal.app (without
+        Option=Meta config) sends Unicode Ω / ÷. Bind those characters
+        too as a fallback so the menu fires anyway."""
+        from omega_engine.tmux import _PRO_CONFIG, _DEFAULT_CONFIG
+        for name, cfg in (("_PRO_CONFIG", _PRO_CONFIG),
+                          ("_DEFAULT_CONFIG", _DEFAULT_CONFIG)):
+            self.assertIn('"Ω"', cfg,
+                f"{name} must bind the literal Ω character (Option+Z on macOS) "
+                f"as a fallback for terminals without Option=Meta config")
+            self.assertIn('"÷"', cfg,
+                f"{name} must bind the literal ÷ character (Option+/ on macOS)")
+
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)

package/omega/Agentik_Engine/tests/test_v19_53_cli_commands.py

@@ -0,0 +1,351 @@
+"""Regression tests for v0.19.53 — ``omega hermes`` and ``omega paperclip``
+must produce user-friendly output (or open the chat session), NEVER crash
+with a raw Python traceback.
+
+User-reported bug on a fresh Mac install (v0.19.51): both commands
+"don't work". Diagnosis traced two distinct issues:
+
+  Bug 1 — UnboundLocalError in ``cmd_hermes``
+  --------------------------------------------
+  ``omega hermes ask "anything"`` crashed with::
+
+      UnboundLocalError: cannot access local variable 'sys' where it
+      is not associated with a value
+
+  Root cause: the ``chat-loop`` branch had ``import os, sys`` inside
+  the function. Python's static-binding rule then treated ``sys``
+  (and ``os``) as local to the WHOLE function — so the ``ask`` /
+  ``env`` / ``brief observe`` / help-fallback branches blew up when
+  their ``except HermesError`` handler tried ``print(..., file=
+  sys.stderr)``.
+
+  Visible consequence on a fresh install (where Hermes is not yet
+  installed, so ``H.ask`` raises ``HermesError``): the user saw a
+  raw 15-line Python traceback instead of the intended friendly
+  ``error: \\`hermes\\` not on PATH — run \\`omega hermes install\\``.
+
+  Fix (cli.py only): remove the redundant ``import os, sys`` from
+  the ``chat-loop`` branch — both are already imported at module
+  scope.
+
+  Bug 2 — paperclip works but the test surface had no regression
+  ---------------------------------------------------------------
+  ``omega paperclip`` (no subcommand) and ``omega paperclip status``
+  already produce friendly output on an un-installed Paperclip
+  (defaulting to ``status`` via ``sub = ... or "status"``). We lock
+  that behaviour in so a future refactor cannot regress it.
+
+Each test exercises the user-visible behaviour, not implementation
+details — a later refactor of the friendly-error wording is fine as
+long as the command still exits cleanly with help, not a traceback.
+"""
+from __future__ import annotations
+
+import io
+import os
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+
+HERE = Path(__file__).resolve().parent
+ENGINE_ROOT = HERE.parent
+
+# Make sure ``omega_engine`` is importable even when pytest is run from
+# the project root.
+sys.path.insert(0, str(ENGINE_ROOT))
+
+
+def _run_omega(argv: list[str]) -> tuple[int, str, str]:
+    """Invoke ``omega_engine.cli.main`` in-process with the given argv.
+
+    Returns ``(rc, stdout, stderr)``. Swallows ``SystemExit`` so callers
+    can assert on the exit code without an exception bubbling up.
+    """
+    from omega_engine.cli import main
+
+    out, err = io.StringIO(), io.StringIO()
+    rc = 0
+    saved_argv = sys.argv[:]
+    sys.argv = ["omega"] + argv
+    try:
+        with redirect_stdout(out), redirect_stderr(err):
+            try:
+                rc = main()
+            except SystemExit as exc:  # argparse exits via SystemExit
+                rc = int(exc.code or 0)
+    finally:
+        sys.argv = saved_argv
+    return rc, out.getvalue(), err.getvalue()
+
+
+class TestHermesCLI(unittest.TestCase):
+    """`omega hermes ...` must never print a raw traceback."""
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.mkdtemp(prefix="omega-test-")
+        self._home = Path(self._tmp) / "Omega"
+        (self._home / "Agentik_Extra" / "var" / "logs").mkdir(
+            parents=True, exist_ok=True
+        )
+        self._env_patch = mock.patch.dict(
+            os.environ, {"OMEGA_HOME": str(self._home)}, clear=False,
+        )
+        self._env_patch.start()
+
+    def tearDown(self) -> None:
+        self._env_patch.stop()
+        import shutil as _sh
+        _sh.rmtree(self._tmp, ignore_errors=True)
+
+    # ------------------------------------------------------------------
+    # Bug 1 — UnboundLocalError regression (the headline fix)
+    # ------------------------------------------------------------------
+    def test_omega_hermes_ask_with_no_hermes_installed_gives_friendly_error(
+        self,
+    ) -> None:
+        """When hermes is not on PATH (fresh install), ``omega hermes ask``
+        MUST print a friendly one-liner and exit non-zero — NOT crash
+        with ``UnboundLocalError: ... 'sys'``.
+        """
+        from omega_engine import hermes as H
+
+        # Simulate "hermes binary not installed" — ``H.ask`` raises
+        # HermesError. The cli handler must catch it and print a hint.
+        with mock.patch.object(
+            H, "ask",
+            side_effect=H.HermesError(
+                "`hermes` not on PATH — run `omega hermes install`"
+            ),
+        ):
+            rc, out, err = _run_omega(["hermes", "ask", "hi"])
+
+        # The bug was UnboundLocalError — surface it loudly if it ever
+        # comes back.
+        full = out + err
+        self.assertNotIn("UnboundLocalError", full,
+                         msg=f"UnboundLocalError regression:\n{full}")
+        self.assertNotIn("Traceback", full,
+                         msg=f"raw traceback leaked to user:\n{full}")
+        # Friendly hint must be on stderr (where the handler writes it).
+        self.assertIn("hermes", err.lower())
+        # And we exit with rc=2 (the existing contract for an ask failure).
+        self.assertEqual(rc, 2)
+
+    def test_omega_hermes_env_friendly_error_when_creds_unavailable(self) -> None:
+        """`omega hermes env` MUST handle ``HermesError`` from ``build_env``
+        without crashing on ``sys`` being unbound.
+        """
+        from omega_engine import hermes as H
+
+        with mock.patch.object(
+            H, "build_env",
+            side_effect=H.HermesError("no Claude OAuth token found"),
+        ):
+            rc, out, err = _run_omega(["hermes", "env"])
+
+        full = out + err
+        self.assertNotIn("UnboundLocalError", full)
+        self.assertNotIn("Traceback", full)
+        self.assertEqual(rc, 2)
+        self.assertIn("no Claude OAuth token", err)
+
+    # ------------------------------------------------------------------
+    # `omega hermes status` — should always work, even without hermes
+    # ------------------------------------------------------------------
+    def test_omega_hermes_status_renders_without_crashing(self) -> None:
+        """`omega hermes status` reads the in-process probe and prints a
+        snapshot. It must succeed even if hermes is not installed.
+        """
+        rc, out, err = _run_omega(["hermes", "status"])
+
+        self.assertNotIn("UnboundLocalError", out + err)
+        self.assertNotIn("Traceback", out + err)
+        # Exit code 0 (all green) or 1 (something missing) — both are
+        # legitimate; what matters is no crash.
+        self.assertIn(rc, (0, 1))
+        # Output mentions the canonical fields.
+        self.assertIn("hermes", out.lower())
+
+    def test_omega_hermes_status_json_emits_parsable_json(self) -> None:
+        """`omega hermes status --json` must emit valid JSON, not a
+        traceback — used by external tooling.
+        """
+        import json as _json
+
+        rc, out, err = _run_omega(["hermes", "status", "--json"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertIn(rc, (0, 1))
+        # The JSON object lives on stdout. Parse the first complete
+        # JSON document we find (the handler emits one indented object).
+        try:
+            parsed = _json.loads(out)
+        except _json.JSONDecodeError as exc:
+            self.fail(f"--json did not produce parseable JSON: {exc}\n{out!r}")
+        self.assertIn("installed", parsed)
+        self.assertIn("hermes_home", parsed)
+
+    # ------------------------------------------------------------------
+    # `omega hermes install --dry-run` — must not actually run install.sh
+    # ------------------------------------------------------------------
+    def test_omega_hermes_install_dry_run_prints_command(self) -> None:
+        """`omega hermes install --dry-run` prints the curl command it
+        WOULD run, exits 0, and does NOT crash.
+        """
+        rc, out, err = _run_omega(["hermes", "install", "--dry-run"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertEqual(rc, 0)
+        # Either "dry-run" appears or the install URL — both prove the
+        # branch executed.
+        self.assertTrue(
+            "dry-run" in out.lower() or "github" in out.lower(),
+            msg=f"unexpected output:\n{out}",
+        )
+
+
+class TestPaperclipCLI(unittest.TestCase):
+    """`omega paperclip` must default to a useful status snapshot, and
+    its subcommands must never blow up with a Python traceback."""
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.mkdtemp(prefix="omega-test-")
+        self._home = Path(self._tmp) / "Omega"
+        self._pc_home = Path(self._tmp) / ".paperclip"
+        (self._home / "Agentik_Extra" / "var" / "logs").mkdir(
+            parents=True, exist_ok=True
+        )
+        self._env_patch = mock.patch.dict(
+            os.environ,
+            {
+                "OMEGA_HOME": str(self._home),
+                "PAPERCLIP_HOME": str(self._pc_home),
+            },
+            clear=False,
+        )
+        self._env_patch.start()
+
+    def tearDown(self) -> None:
+        self._env_patch.stop()
+        import shutil as _sh
+        _sh.rmtree(self._tmp, ignore_errors=True)
+
+    def test_omega_paperclip_no_args_runs_status_without_crashing(self) -> None:
+        """Bare ``omega paperclip`` (no subcommand) MUST default to
+        ``status`` and render a snapshot — not crash, not show argparse
+        help (which exits non-zero from the user's POV).
+        """
+        rc, out, err = _run_omega(["paperclip"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertEqual(rc, 0)
+        # Status output mentions the canonical fields.
+        self.assertIn("paperclip", out.lower())
+        self.assertIn("agents registered", out.lower())
+
+    def test_omega_paperclip_status_renders_canonical_fields(self) -> None:
+        """`omega paperclip status` always prints the 7 canonical fields:
+        installed / paperclip_home / omegaos company / agents registered /
+        workspaces / heartbeats pending / bridge_version."""
+        rc, out, err = _run_omega(["paperclip", "status"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertEqual(rc, 0)
+        low = out.lower()
+        for needle in (
+            "paperclip installed",
+            "paperclip_home",
+            "omegaos company",
+            "agents registered",
+            "workspaces",
+            "heartbeats pending",
+            "bridge_version",
+        ):
+            self.assertIn(needle, low,
+                          msg=f"missing field {needle!r} in:\n{out}")
+
+    def test_omega_paperclip_register_dry_run_writes_14_agents(self) -> None:
+        """`omega paperclip register --dry-run` must report 14 agents
+        written (Hermès + 13 AISB suite — the contract from v0.19.33)."""
+        rc, out, err = _run_omega(["paperclip", "register", "--dry-run"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertEqual(rc, 0)
+        # Output is `key: value` lines from PB.register's summary dict.
+        self.assertIn("agents_written: 14", out)
+        self.assertIn("dry_run: True", out)
+
+    def test_omega_paperclip_url_default_loopback(self) -> None:
+        """`omega paperclip url` prints a dashboard URL, no traceback."""
+        rc, out, err = _run_omega(["paperclip", "url"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertEqual(rc, 0)
+        self.assertIn("paperclip dashboard", out.lower())
+
+    def test_omega_paperclip_remote_setup_prints_help(self) -> None:
+        """`omega paperclip remote-setup` prints the SSH/Tailscale/Tunnel
+        instructions without crashing."""
+        rc, out, err = _run_omega(["paperclip", "remote-setup"])
+        self.assertNotIn("Traceback", out + err)
+        self.assertEqual(rc, 0)
+        self.assertGreater(len(out.strip()), 0,
+                           msg="remote-setup produced no output")
+
+
+class TestCmdHermesNoLocalImports(unittest.TestCase):
+    """White-box guard: ensure ``cmd_hermes`` never re-imports ``sys`` or
+    ``os`` in a way that would shadow the module-level imports.
+
+    This is the structural invariant that catches Bug 1 at the source.
+    If a future commit adds ``import sys`` (or ``import os, sys``, or
+    ``from sys import ...``) inside ``cmd_hermes``, this test fails
+    immediately, with a clear pointer to the v0.19.53 root cause.
+    """
+
+    def test_cmd_hermes_does_not_reimport_sys_or_os_locally(self) -> None:
+        import ast
+        import inspect
+
+        from omega_engine import cli as _cli
+
+        src = inspect.getsource(_cli.cmd_hermes)
+        # Trim leading indentation so ast.parse can handle the snippet.
+        import textwrap
+        tree = ast.parse(textwrap.dedent(src))
+
+        offenders: list[str] = []
+
+        class _Visitor(ast.NodeVisitor):
+            def visit_Import(self, node: ast.Import) -> None:  # noqa: N802
+                for alias in node.names:
+                    if alias.name in {"sys", "os"} and alias.asname is None:
+                        offenders.append(
+                            f"line {node.lineno}: `import {alias.name}` "
+                            f"shadows module-level import"
+                        )
+
+            def visit_ImportFrom(  # noqa: N802
+                self, node: ast.ImportFrom,
+            ) -> None:
+                if node.module in {"sys", "os"}:
+                    for alias in node.names:
+                        if alias.asname is None and alias.name != "*":
+                            offenders.append(
+                                f"line {node.lineno}: "
+                                f"`from {node.module} import {alias.name}`"
+                            )
+
+        _Visitor().visit(tree)
+        self.assertEqual(
+            offenders, [],
+            msg=(
+                "cmd_hermes re-imports `sys` / `os` locally — this "
+                "shadows the module-level imports and breaks branches "
+                "that reference them in `except` handlers (the v0.19.53 "
+                "UnboundLocalError bug). Offenders:\n  "
+                + "\n  ".join(offenders)
+            ),
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

package/omega/Agentik_SSOT/VERSION

@@ -1 +1 @@
-0.19.52
+0.19.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentikos/omega-os",
-  "version": "0.19.52",
+  "version": "0.19.54",
   "description": "Omega OS — installable agentic operating system with verified-completion orchestration. Event-sourced engine, 8-block rack, autonomous agents, MCP.",
   "bin": {
     "omega-os": "bin/omega-os.js"