@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/skill_discovery/installer.py

@@ -0,0 +1,129 @@
+"""Validated skill installer — audit before write.
+
+Two paths a skill can come from:
+
+  1. The Claude Code plugin marketplace (``claude plugin install
+     <name>@<marketplace>``). Step 45 of the OmegaOS installer handles
+     this for the curated list. We don't duplicate that path here.
+
+  2. Direct from a GitHub repo — `omega skill install <name>
+     --from github:<org>/<repo>[/<path>]`. We clone, locate the
+     ``SKILL.md``, run the auditor, and only on a clean verdict copy
+     it into ``Agentik_SSOT/skills/<name>/``. ``omega sync`` then
+     projects it to ``~/.claude/skills/``.
+
+We refuse to install if the auditor returns ``verified=False`` unless
+the operator explicitly passes ``allow_blocked=True``.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from omega_engine.skill_discovery.auditor import (
+    SkillAuditVerdict,
+    audit_skill_file,
+)
+
+
+@dataclass
+class SkillInstallResult:
+    skill_name: str
+    installed: bool
+    skill_path: Path | None
+    audit: SkillAuditVerdict | None = None
+    reason: str = ""
+
+
+def _clone(repo: str, dest: Path) -> bool:
+    """Shallow-clone a GitHub repo into ``dest``. Returns True on success."""
+    proc = subprocess.run(
+        ["git", "clone", "--depth", "1",
+         f"https://github.com/{repo}.git", str(dest)],
+        check=False, capture_output=True, text=True, timeout=120,
+    )
+    return proc.returncode == 0
+
+
+def install_skill_from_github(
+    omega_home: str | Path,
+    skill_name: str,
+    *,
+    repo: str,
+    sub_path: str = "",
+    allow_blocked: bool = False,
+) -> SkillInstallResult:
+    """Install one skill from a GitHub repo.
+
+    Args:
+        omega_home: ``$OMEGA_HOME`` — destination is
+            ``$OMEGA_HOME/Agentik_SSOT/skills/<skill_name>/``.
+        skill_name: the directory name the skill will live under.
+        repo: ``org/repo`` (no ``github:`` prefix; no URL).
+        sub_path: optional path inside the repo where the SKILL.md
+            lives (e.g. ``skills/find-skills``). If empty, we try
+            ``skills/<skill_name>/`` then the repo root.
+        allow_blocked: install even if the auditor returns
+            ``verified=False``. Hard-fail by default.
+
+    Returns: ``SkillInstallResult``.
+    """
+    home = Path(omega_home)
+    target = home / "Agentik_SSOT" / "skills" / skill_name
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        clone_dir = tmp_path / "src"
+        if not _clone(repo, clone_dir):
+            return SkillInstallResult(
+                skill_name=skill_name, installed=False, skill_path=None,
+                reason=f"git clone github:{repo} failed",
+            )
+
+        # Find the SKILL.md.
+        candidates = []
+        if sub_path:
+            candidates.append(clone_dir / sub_path / "SKILL.md")
+        candidates += [
+            clone_dir / "skills" / skill_name / "SKILL.md",
+            clone_dir / skill_name / "SKILL.md",
+            clone_dir / "SKILL.md",
+        ]
+        skill_md = next((p for p in candidates if p.exists()), None)
+        if skill_md is None:
+            return SkillInstallResult(
+                skill_name=skill_name, installed=False, skill_path=None,
+                reason=f"no SKILL.md found in {repo} "
+                f"(looked at {[str(c.relative_to(clone_dir)) for c in candidates]})",
+            )
+
+        # Audit.
+        verdict = audit_skill_file(skill_md)
+        if not verdict.verified and not allow_blocked:
+            return SkillInstallResult(
+                skill_name=skill_name, installed=False, skill_path=None,
+                audit=verdict,
+                reason=(
+                    f"audit blocked install: {verdict.block_count} block + "
+                    f"{verdict.warn_count} warn issue(s)"
+                ),
+            )
+
+        # Copy the skill directory (SKILL.md + any siblings — scripts/, examples/).
+        skill_dir = skill_md.parent
+        target.mkdir(parents=True, exist_ok=True)
+        for item in skill_dir.iterdir():
+            dest = target / item.name
+            if item.is_dir():
+                if dest.exists():
+                    shutil.rmtree(dest)
+                shutil.copytree(item, dest)
+            else:
+                shutil.copy(item, dest)
+        return SkillInstallResult(
+            skill_name=skill_name, installed=True, skill_path=target,
+            audit=verdict,
+        )

package/omega/Agentik_Engine/omega_engine/skill_discovery/marketplaces.py

@@ -0,0 +1,80 @@
+"""Marketplace catalog — every trusted source of Claude Code skills.
+
+The catalog itself lives in YAML at
+``Agentik_SSOT/claude-plugins/claude-plugins.yaml`` (extended in this
+PR with ``trust`` and a few non-builtin marketplaces). This module
+loads + filters it.
+
+Trust levels:
+
+  * ``high``   — Anthropic, Vercel Labs, other vetted vendors. Auditor
+                 still runs but warnings rarely block.
+  * ``medium`` — community marketplaces (davila7, thedotmack, etc.).
+                 Auditor warnings get surfaced to the operator.
+  * ``low``    — random GitHub repos. Auditor hard-fails on anything
+                 suspicious.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class Marketplace:
+    id: str
+    source: str
+    description: str
+    trust: str = "medium"        # "high" | "medium" | "low"
+    builtin: bool = False
+
+    @property
+    def is_github(self) -> bool:
+        return self.source.startswith("github:")
+
+    @property
+    def github_repo(self) -> str | None:
+        if not self.is_github:
+            return None
+        return self.source.split(":", 1)[1]
+
+    @property
+    def github_url(self) -> str | None:
+        repo = self.github_repo
+        return f"https://github.com/{repo}" if repo else None
+
+
+def load_marketplaces(omega_home: str | Path) -> list[Marketplace]:
+    """Read the marketplace list from the SSOT catalog."""
+    path = (Path(omega_home) / "Agentik_SSOT" / "claude-plugins"
+            / "claude-plugins.yaml")
+    if not path.exists():
+        return []
+    data = yaml.safe_load(path.read_text()) or {}
+    out: list[Marketplace] = []
+    for m in data.get("marketplaces") or []:
+        out.append(Marketplace(
+            id=m["id"],
+            source=m.get("source", ""),
+            description=m.get("description", ""),
+            trust=m.get("trust", "medium"),
+            builtin=bool(m.get("builtin", False)),
+        ))
+    return out
+
+
+def get_marketplace(
+    omega_home: str | Path, marketplace_id: str,
+) -> Marketplace | None:
+    for m in load_marketplaces(omega_home):
+        if m.id == marketplace_id:
+            return m
+    return None
+
+
+def trust_floor(trust: str) -> int:
+    """Numeric trust floor — higher = more trust."""
+    return {"high": 3, "medium": 2, "low": 1}.get(trust.lower(), 0)

package/omega/Agentik_Engine/omega_engine/skill_routing.py

@@ -0,0 +1,388 @@
+"""Role → skills routing.
+
+Why this module exists
+----------------------
+
+OmegaOS ships 24 first-party skills (17 audits + dispatch + pursue + cadence
++ skill-finder/auditor + rag-route). Anthropic's catalog grows weekly. A
+worker spawned with EVERY skill available has its context bloated with
+descriptions it'll never use — and Claude gets confused about which to
+reach for.
+
+The right shape: each role declares the skills it should reach for, and the
+``WorkerBrief.skills`` field becomes the authoritative tool palette. The
+worker's system prompt enumerates those skills + a "use them when
+applicable" instruction so Claude actually engages them.
+
+Topology overrides this per-mission (e.g. a "frontend-fix" mission gives
+the worker only `pursue` + `uiuxaudit` + `a11yaudit`, while a "data-migration"
+mission gives it `pursue` + `dataaudit` + `apiaudit`).
+
+Resolution order (highest wins)
+-------------------------------
+
+  1. Explicit ``brief.skills`` (operator passed --skills)
+  2. Topology declares ``mission_skills`` for the role
+  3. ``_ROLE_SKILLS`` map below (sensible defaults per role)
+  4. Empty list → Claude uses whatever's globally installed
+
+Public API
+----------
+
+  ``skills_for(role, ...)`` returns the resolved list.
+  ``recommend(role)`` returns the role-default for `omega skill recommend`.
+  ``catalog_for_home(home)`` returns every skill id present in the SSOT.
+  ``format_skill_block(skills, home)`` builds the system_prompt snippet
+  embedded by ``spawn_worker``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Role → default skills
+# ---------------------------------------------------------------------------
+#
+# Curated. Not "every skill" — only the ones that role actually benefits from.
+# Each entry is a comment + a list because future maintainers should be able
+# to see the WHY of every line.
+
+_ROLE_SKILLS: dict[str, list[str]] = {
+    # ---------------------------------------------------------------------
+    # Dispatchers — they plan + delegate. They orchestrate but never code.
+    # ``dispatch`` lets them spawn sub-missions; ``pursue`` lets them run
+    # a goal-driven loop directly when planning isn't worth it. ``cadence``
+    # lets them schedule recurring beats. They have the FULL audit catalog
+    # in scope so they can RECOMMEND audits when assigning work.
+    # ---------------------------------------------------------------------
+    "oracle": [
+        "dispatch", "pursue", "cadence",
+        "codeaudit", "debugaudit", "uiuxaudit", "secaudit",
+        "perfaudit", "a11yaudit", "flowaudit", "featureaudit",
+    ],
+    "manager": [
+        "dispatch", "pursue",
+        "codeaudit", "debugaudit", "secaudit", "perfaudit",
+    ],
+    "aisb": [
+        "dispatch", "pursue", "cadence",
+        "codeaudit", "debugaudit", "uiuxaudit", "secaudit",
+    ],
+    "architect": [
+        "dispatch", "pursue",
+        "codeaudit", "logicaudit", "apiaudit", "dataaudit",
+        "secaudit", "perfaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Executors — they DO the work. They get the full audit palette so
+    # they can self-verify BEFORE claiming done (a worker that runs
+    # /codeaudit on its own changes catches its own mistakes — verified
+    # completion shifts left). ``pursue`` is the goal-driven loop.
+    # ---------------------------------------------------------------------
+    "worker": [
+        "pursue",
+        # Core code / runtime
+        "codeaudit", "debugaudit", "logicaudit",
+        # UI / UX (most common worker domain)
+        "uiuxaudit", "a11yaudit", "flowaudit", "motionaudit", "copyaudit",
+        # Cross-cutting checks
+        "perfaudit", "secaudit", "seoaudit",
+    ],
+    "construct": [
+        "pursue",
+        # Build / data / API specialist
+        "codeaudit", "apiaudit", "dataaudit", "logicaudit",
+        "perfaudit", "secaudit", "dxaudit",
+    ],
+    "link": [
+        "pursue",
+        # Integration / external systems
+        "apiaudit", "secaudit", "automationaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Verifiers — read-only; they audit. The bigger the palette, the
+    # harder it is for a worker to hide a regression. Seraph is the
+    # senior verifier — it gets EVERY audit.
+    # ---------------------------------------------------------------------
+    "audit": [
+        "codeaudit", "debugaudit", "secaudit",
+        "perfaudit", "a11yaudit",
+    ],
+    "verifier": [
+        "codeaudit", "debugaudit", "logicaudit",
+    ],
+    "seraph": [
+        "codeaudit", "debugaudit", "uiuxaudit", "secaudit",
+        "perfaudit", "a11yaudit", "seoaudit", "apiaudit", "dataaudit",
+        "flowaudit", "featureaudit", "logicaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Triage / classifier — minimal tool surface. Haiku model, fast pass.
+    # ---------------------------------------------------------------------
+    "classifier": [],
+    "triage":     [],
+
+    # ---------------------------------------------------------------------
+    # Special meta-roles
+    # ---------------------------------------------------------------------
+    "skill_curator":  ["skill-finder", "skill-auditor"],
+    "smith":          [        # Reflection / learning — reads audits
+        "codeaudit", "debugaudit", "retentionaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Domain-specialist worker roles. Operators dispatch to these when a
+    # mission has an obvious primary domain. Each gets pursue + the
+    # domain audit + the 2-3 most relevant cross-cutters.
+    # ---------------------------------------------------------------------
+    "worker_ui":      [
+        "pursue",
+        # Audits — UI domain
+        "uiuxaudit", "a11yaudit", "motionaudit", "copyaudit", "refontaudit",
+        # Design-discipline skills (Genesis writes these into feature briefs;
+        # workers MUST invoke them, not paraphrase them)
+        "shadcn-ui", "emil-design-eng", "impeccable", "taste-skill",
+        "frontend-design", "design-taste-frontend",
+    ],
+    "worker_perf":    ["pursue", "perfaudit", "codeaudit", "debugaudit", "logicaudit"],
+    "worker_sec":     ["pursue", "secaudit", "codeaudit", "apiaudit", "dataaudit"],
+    "worker_api":     ["pursue", "apiaudit", "codeaudit", "dataaudit", "secaudit"],
+    "worker_data":    ["pursue", "dataaudit", "codeaudit", "apiaudit", "secaudit"],
+    "worker_seo":     ["pursue", "seoaudit", "perfaudit", "a11yaudit", "copyaudit"],
+    "worker_ops":     ["pursue", "automationaudit", "dxaudit", "secaudit"],
+    "worker_growth":  ["pursue", "retentionaudit", "featureaudit", "copyaudit"],
+}
+
+
+# Skills the engine treats as "power tools" — operators should know they
+# exist. Surfaced by `omega skill recommend` and the post-install card.
+POWER_SKILLS: list[str] = [
+    "dispatch",      # multi-agent orchestration
+    "pursue",        # goal-driven loop
+    "cadence",       # scheduled / recurring beats
+    "codeaudit",     # is the code SOLID
+    "debugaudit",    # what's broken right now
+    "uiuxaudit",     # is the UI beautiful
+    "secaudit",      # is it secure
+    "perfaudit",     # is it fast
+    "a11yaudit",     # is it accessible
+    "seoaudit",      # is it discoverable
+]
+
+
+# ---------------------------------------------------------------------------
+# Canonical skill-chain workflows.
+#
+# Each entry is a multi-line string describing how skills compose into a
+# complete workflow. ``omega skill workflows`` surfaces these so operators
+# can SEE how /dispatch → /pursue → /codeaudit → fix-workers → re-audit
+# actually chains together at runtime.
+#
+# The content is informative — Claude reads these via the skill block when
+# the role's palette includes the relevant primitives. They are NOT executed
+# as code; they're the canonical playbook.
+# ---------------------------------------------------------------------------
+
+WORKFLOWS: dict[str, str] = {
+    "ship-feature": """\
+Build + verify a feature, end-to-end, with no API-key burn.
+
+  1.  Operator runs:  /dispatch "implement OAuth login with verify against tests/auth.test.ts"
+  2.  /dispatch  →  Oracle plans 3 worker subtasks:
+                      a. add the auth endpoint (worker, with /codeaudit + /apiaudit + /secaudit)
+                      b. update the client form    (worker, with /uiuxaudit + /a11yaudit + /flowaudit)
+                      c. add the playwright test   (worker, with /codeaudit + /flowaudit)
+  3.  Each worker runs /pursue <verify_cmd> until exit 0.
+  4.  Seraph runs /codeaudit + /debugaudit + /secaudit on each .done.json.
+  5.  Mission completes only when EVERY child is VERIFIED (not just CLAIMED_DONE).
+  6.  Smith reflection (autonomous, daily) reads the audit history and writes Insight
+       proposals to Agentik_Extra/staging/promotion/ if anything was weak.
+
+Skills in chain:  /dispatch  →  /pursue  →  /codeaudit  →  fix workers  →  /codeaudit (re-audit)
+""",
+
+    "self-audit-loop": """\
+A worker AUDITS ITS OWN CHANGES before claiming done — verified completion
+shifts left, catching mistakes one layer earlier.
+
+  1.  Worker reads brief, makes the change.
+  2.  BEFORE writing .done.json, worker runs /codeaudit --files=<changed>
+        - If score >= 85 → write done_clean
+        - If score <  85 → fix the findings (loop), then re-audit
+        - Hard cap: 3 iterations, then write `pending` with the unresolved findings
+  3.  Seraph (verifier) re-runs the audit independently.
+        - If Seraph also passes → VERIFIED
+        - If Seraph fails what the worker thought it passed → REJECTED + retry budget
+  4.  Verified completion is now SOLID — two independent passes had to agree.
+
+Skills in chain:  /pursue  →  /codeaudit (self)  →  /codeaudit (verifier)
+""",
+
+    "ux-redesign": """\
+Multi-domain UX redesign with parallel specialised workers.
+
+  1.  Operator:  /refontaudit --url=https://app/dashboard
+                   → produces a redesign plan with /100 score per pillar
+  2.  /dispatch "execute the refontaudit plan; preserve existing functionality"
+       → Oracle spawns 4 worker_ui's in parallel, file ownership disjoint:
+           a. layout shell             (worker_ui  + /uiuxaudit)
+           b. component primitives     (worker_ui  + /a11yaudit)
+           c. motion + transitions     (worker_ui  + /motionaudit)
+           d. copy + microcopy         (worker_ui  + /copyaudit)
+  3.  Each worker /pursue <playwright-screenshot-diff> until 0 visual regressions.
+  4.  Seraph runs FULL audit pass (12 audits) on the final state.
+  5.  Mission verified only if every audit >= threshold.
+
+Skills in chain:  /refontaudit  →  /dispatch  →  4× /pursue + /uiuxaudit/a11yaudit/motionaudit/copyaudit
+""",
+
+    "linear-fix-batch": """\
+Fix N Linear tickets in parallel-safe batches (the v0.10 pattern).
+
+  1.  Operator:  /dispatch "fix all 36 Linear feedback tickets in this project"
+  2.  Oracle calls linear-conflict-analyzer.py → annotates each ticket with
+       files_touched + conflict_class (narrow | broad | terminal).
+  3.  Oracle greedy-packs up to 4 NARROW tickets with disjoint file footprints
+       into one batch; BROAD tickets run alone.
+  4.  Per ticket, worker runs:
+        - Playwright BEFORE capture (visual + console baseline)
+        - implement fix
+        - Playwright AFTER capture
+        - /codeaudit --files=<changed>  (self-audit)
+        - write .done.json with Before/After paths
+  5.  Seraph runs /debugaudit on each ticket  →  VERIFIED or REJECTED.
+  6.  After each batch, `npm run build` once.
+  7.  Next batch dispatches; repeat until queue empty.
+
+Skills in chain:  /dispatch  →  /pursue per ticket  →  /codeaudit  →  /debugaudit
+""",
+
+    "scheduled-quality": """\
+Continuously running quality watch via cron + /cadence.
+
+  1.  Operator:  /cadence schedule cron "0 3 * * *" \\
+                   "run the full forensic audit suite on $project, write the report,
+                    create Linear tickets for findings >= high severity"
+  2.  Every night at 03:00, autonomous-supervisor fires the charter.
+  3.  Engine dispatches a verifier with the full audit palette (12 audits).
+  4.  Failing audits → Insight files in Agentik_Extra/staging/promotion/.
+  5.  Smith reflection (also daily) reads the trend → proposes which audits
+       to dispatch fix-workers for first.
+
+Skills in chain:  /cadence  →  daily cron  →  /dispatch verifier  →  12 audits  →  Smith insight
+""",
+}
+
+
+def recommend(role: str) -> list[str]:
+    """Default skill list for a role. Empty list if the role is unknown."""
+    return list(_ROLE_SKILLS.get(role, []))
+
+
+def skills_for(
+    role: str,
+    *,
+    explicit: list[str] | None = None,
+    topology_skills: list[str] | None = None,
+) -> list[str]:
+    """Resolve the final skill list for a worker (precedence order documented above)."""
+    if explicit:
+        return list(explicit)
+    if topology_skills:
+        return list(topology_skills)
+    return recommend(role)
+
+
+def catalog_for_home(home: str | Path) -> list[str]:
+    """Every skill id present under ``$OMEGA_HOME/Agentik_SSOT/skills/``."""
+    root = Path(home) / "Agentik_SSOT" / "skills"
+    if not root.is_dir():
+        return []
+    out: list[str] = []
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and (child / "SKILL.md").exists():
+            out.append(child.name)
+        elif child.is_file() and child.suffix == ".md":
+            out.append(child.stem)
+    return out
+
+
+def format_skill_block(
+    skills: list[str], home: str | Path | None = None,
+) -> str:
+    """Build the system_prompt snippet that tells the worker which skills it
+    should reach for. Empty list → empty string (worker uses ambient skills).
+
+    Output shape:
+
+        ## Skills available
+
+        You have these OmegaOS skills available — invoke them as slash
+        commands when applicable:
+
+          /pursue <verify-cmd> <intent>       — goal-driven loop
+          /codeaudit --files=...              — forensic code audit
+          ...
+
+        Prefer these over ad-hoc Bash whenever they fit. Do not paraphrase
+        an audit protocol into raw prompts.
+    """
+    if not skills:
+        return ""
+
+    # Build short descriptions from the SSOT SKILL.md if available; otherwise
+    # we just list the names.
+    descs: dict[str, str] = {}
+    if home is not None:
+        root = Path(home) / "Agentik_SSOT" / "skills"
+        for s in skills:
+            md = root / s / "SKILL.md"
+            if not md.is_file():
+                md = root / f"{s}.md"
+            if md.is_file():
+                d = _extract_description(md)
+                if d:
+                    descs[s] = d
+
+    lines = ["", "## Skills available", ""]
+    lines.append(
+        "You have these OmegaOS skills available — invoke them as slash"
+    )
+    lines.append("commands when applicable:")
+    lines.append("")
+    for s in skills:
+        desc = descs.get(s, "")
+        if desc:
+            # Truncate to one line for compactness.
+            desc_line = desc.replace("\n", " ").strip()
+            if len(desc_line) > 110:
+                desc_line = desc_line[:107] + "..."
+            lines.append(f"  /{s}  — {desc_line}")
+        else:
+            lines.append(f"  /{s}")
+    lines.append("")
+    lines.append(
+        "Prefer these over ad-hoc Bash whenever they fit. Do not paraphrase"
+    )
+    lines.append("an audit protocol into raw prompts — invoke the slash command.")
+    return "\n".join(lines)
+
+
+def _extract_description(skill_md: Path) -> str:
+    """Pull the `description:` field from a SKILL.md frontmatter."""
+    try:
+        text = skill_md.read_text()
+    except OSError:
+        return ""
+    if not text.startswith("---"):
+        return ""
+    # Manual minimal YAML — avoid the PyYAML dep on this hot path.
+    body = text.split("---", 2)[1] if text.count("---") >= 2 else ""
+    for line in body.splitlines():
+        if line.startswith("description:"):
+            return line.split(":", 1)[1].strip().strip('"').strip("'")
+    return ""

package/omega/Agentik_Engine/omega_engine/smoke.py

@@ -0,0 +1,81 @@
+"""`omega smoke` — 30-second post-install end-to-end check.
+
+Runs a synthetic mission against the live engine using the deterministic
+MockProvider. The mission is intentionally tiny: one Oracle, one Worker,
+one Verifier. Pass = events flow + .done.json written + audit gate
+returned VERIFIED. Fail = something in the orchestration stack is
+broken and the operator's first real mission would too.
+
+Exit code 0 on smoke pass, 1 on fail. Designed for CI / cron / install
+post-step.
+"""
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SmokeResult:
+    passed: bool
+    elapsed_ms: int
+    mission_id: str = ""
+    final_state: str = ""
+    events_recorded: int = 0
+    done_files_written: int = 0
+    detail: str = ""
+
+
+def run_smoke(*, omega_home: str | Path | None = None) -> SmokeResult:
+    """One synthetic mission. Always uses MockProvider — no API keys needed.
+
+    The goal is "the orchestration stack itself works", not "your API
+    keys are valid" (that's ``omega validate providers``).
+    """
+    home = Path(omega_home or os.environ.get("OMEGA_HOME")
+                or Path.home() / "Omega")
+    start = time.time()
+    try:
+        from omega_engine.audit import AuditGate
+        from omega_engine.bus import EventBus
+        from omega_engine.executor import Executor
+        from omega_engine.provider import MockProvider
+        from omega_engine.router import ModelRouter
+        from omega_engine.store import SQLiteStore
+
+        store_path = home / "Agentik_Runtime" / "eventlog" / "omega.db"
+        store_path.parent.mkdir(parents=True, exist_ok=True)
+        store = SQLiteStore(store_path)
+        bus = EventBus(store)
+        router = ModelRouter.single(MockProvider())
+        executor = Executor(store, bus, router, AuditGate(),
+                            partial_policy="accept_partial")
+        outcome = executor.run_mission(
+            "OmegaOS smoke test — synthetic mission, no real work expected",
+            root_role="oracle",
+        )
+        events = store.events_for(outcome.root.id)
+        # how many .done.json files landed in the per-task session dirs
+        sess = home / "Agentik_Runtime" / "sessions"
+        done = sum(1 for p in sess.rglob(".done.json")) if sess.is_dir() else 0
+        store.close()
+
+        return SmokeResult(
+            passed=outcome.verified,
+            elapsed_ms=int((time.time() - start) * 1000),
+            mission_id=outcome.mission_id,
+            final_state=outcome.final_state.value,
+            events_recorded=len(events),
+            done_files_written=done,
+            detail=("orchestration stack healthy" if outcome.verified
+                    else f"mission ended {outcome.final_state.value}"),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return SmokeResult(
+            passed=False,
+            elapsed_ms=int((time.time() - start) * 1000),
+            detail=f"smoke crashed: {exc}"[:300],
+        )