@agentikos/omega-os 0.19.32 → 0.19.34

package/omega/Agentik_Engine/omega_engine/__init__.py

@@ -188,7 +188,7 @@ from omega_engine.genesis import (
 )
 from omega_engine import plan as plan_v7
 
-__version__ = "0.19.32"
+__version__ = "0.19.34"
 
 __all__ = [
     "__version__",

package/omega/Agentik_Engine/omega_engine/cli.py

@@ -3171,6 +3171,78 @@ def _set_active_provider(provider_id: str) -> None:
     p.write_text(provider_id.strip() + "\n")
 
 
+def cmd_paperclip(args: argparse.Namespace) -> int:
+    """`omega paperclip {status,register,sync,start,heartbeat}` — bridge to
+    paperclipai/paperclip (governance layer L0).
+
+    Lets the Paperclip web dashboard see OmegaOS's 14 agents (Hermès + 13
+    AISB suite), every Genesis project as a workspace, and heartbeats
+    from running tmux sessions. Paperclip stays a parallel system — we
+    don't host Paperclip's server; we just write its config files +
+    drop heartbeats it picks up.
+    """
+    from omega_engine import paperclip_bridge as PB
+    sub = getattr(args, "paperclip_cmd", None) or "status"
+
+    if sub == "status":
+        st = PB.status()
+        print(f"  paperclip installed:  {'✓' if st.paperclip_installed else '—'}")
+        print(f"  paperclip_home:       {st.paperclip_home}")
+        print(f"  omegaos company:      {'✓' if st.company_registered else '—'}  "
+              f"{st.company_dir}")
+        print(f"  agents registered:    {st.agents_registered} / 14")
+        print(f"  workspaces:           {st.workspaces_registered}")
+        print(f"  heartbeats pending:   {st.heartbeats_pending}")
+        print(f"  bridge_version:       {st.bridge_version}")
+        print(f"  omega_version:        {st.omega_version}")
+        if st.drift:
+            print(f"  {st.drift = !r} — run `omega paperclip register` to refresh")
+        if not st.paperclip_installed:
+            print()
+            print("  paperclip not installed — opt-in CLI:")
+            print("    omega tool install paperclipai")
+            print("    omega paperclip register   # register OmegaOS company")
+            print("    omega paperclip start      # spin up the web dashboard")
+        return 0
+
+    if sub == "register":
+        summary = PB.register(dry_run=getattr(args, "dry_run", False))
+        for k, v in summary.items():
+            print(f"  {k}: {v}")
+        return 0
+
+    if sub == "start":
+        bind = getattr(args, "bind", None) or "loopback"
+        try:
+            pid = PB.start_server(bind=bind, detach=True)
+            print(f"  paperclip launched (pid {pid}, bind={bind})")
+            print("  default URL: http://localhost:8080 — check Paperclip output")
+            return 0
+        except RuntimeError as exc:
+            print(f"  start failed: {exc}")
+            return 2
+
+    if sub == "heartbeat":
+        # Drop a heartbeat from the current shell — used by `dispatch-to-
+        # session.sh` style scripts so Paperclip sees workers come up + report.
+        from omega_engine import paperclip_bridge as PB2
+        hb = PB2.Heartbeat(
+            agent_id=getattr(args, "agent_id", "unknown"),
+            project=getattr(args, "project", ""),
+            session=getattr(args, "session", os.environ.get("TMUX_PANE", "")),
+            status=getattr(args, "status", "alive"),
+            summary=getattr(args, "summary", ""),
+            cost_so_far_usd=float(getattr(args, "cost", 0.0)),
+            omega_home=os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")),
+        )
+        ok = PB2.send_heartbeat(hb)
+        print(f"  heartbeat: {'✓' if ok else '✗'}  {hb.agent_id} → {hb.status}")
+        return 0 if ok else 1
+
+    print(f"unknown paperclip subcommand: {sub}")
+    return 2
+
+
 def cmd_scrape(args: argparse.Namespace) -> int:
     """`omega scrape <url> [--engine cloak|scrapling] [--out file]` — scraper.
 
@@ -4453,6 +4525,36 @@ def _build_parser() -> argparse.ArgumentParser:
                       help="provider id (omit to print current + available)")
     p_sw.set_defaults(fn=cmd_switch)
 
+    # `omega paperclip` — governance bridge to paperclipai/paperclip (L0).
+    p_pc = sub.add_parser(
+        "paperclip",
+        help="bridge to Paperclip governance layer (register OmegaOS as "
+        "a Paperclip company, sync projects, send heartbeats)",
+    )
+    p_pc.set_defaults(fn=cmd_paperclip)
+    pc_sub = p_pc.add_subparsers(dest="paperclip_cmd")
+    pc_sub.add_parser("status", help="show bridge health + counts")
+    p_pcr = pc_sub.add_parser("register",
+        help="write Paperclip company.json + agents/<id>.json + workspaces/")
+    p_pcr.add_argument("--dry-run", action="store_true")
+    p_pcs = pc_sub.add_parser("start",
+        help="launch the Paperclip web dashboard (npx onboard)")
+    p_pcs.add_argument("--bind", choices=["loopback", "lan", "tailnet"],
+                       default="loopback")
+    p_pch = pc_sub.add_parser("heartbeat",
+        help="send a heartbeat from a tmux session (script callable)")
+    p_pch.add_argument("--agent-id", required=True,
+                       help="hermes / niobe / oracle / construct / …")
+    p_pch.add_argument("--project", default="",
+                       help="project slug if applicable")
+    p_pch.add_argument("--session", default="",
+                       help="tmux session name (defaults to $TMUX_PANE)")
+    p_pch.add_argument("--status", default="alive",
+                       choices=["alive", "working", "done_clean", "failed"])
+    p_pch.add_argument("--summary", default="")
+    p_pch.add_argument("--cost", default="0",
+                       help="cost so far in USD (float)")
+
     # `omega scrape <url>` — official OmegaOS web scraper (CloakBrowser
     # default, Scrapling optional). Both engines pre-installed at step 40
     # when their catalog entry is `recommended: true`.

package/omega/Agentik_Engine/omega_engine/paperclip_bridge.py

@@ -0,0 +1,510 @@
+"""Paperclip ↔ OmegaOS bridge (v0.19.33).
+
+Registers the OmegaOS agent hierarchy (Hermès + 13 AISB suite) as
+Paperclip agents, mirrors Genesis projects into Paperclip workspaces,
+and sends heartbeats from our tmux sessions into Paperclip's wakeup
+queue. After registration, the Paperclip web dashboard surfaces every
+OmegaOS agent / project / mission with its full org-chart + budget +
+audit trail.
+
+Layered model after this bridge lands:
+
+  Layer 0 — PAPERCLIP            governance + org-chart + budgets + UI
+                                 (https://paperclip.dev)
+  Layer 1 — HUMAN                Telegram / TUI / CLI
+  Layer 2 — HERMÈS               meta-companion (Anthropic API, own bot)
+  Layer 3 — AISB (intake)        Telegram-first classifier → oracle dispatch
+  Layer 4 — ORACLE               per-project planner (Claude Max OAuth)
+  Layer 5 — WORKERS              executors (one per subtask, .done.json)
+
+Paperclip surfaces L1–L5 in its dashboard. Hermès still operates on its
+own Anthropic budget; AISB/Oracle/Workers stay on Max OAuth. Paperclip
+sees BOTH credential domains via its "agent bring own runtime" model.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# The OmegaOS canonical agent hierarchy
+# ---------------------------------------------------------------------------
+
+# Hermès sits ABOVE AISB in the OmegaOS architecture but reports to no-one
+# inside Paperclip's org chart — it's the "COO" of the company.
+HERMES_AGENT = {
+    "id": "hermes",
+    "title": "Hermès — Meta-Companion / COO",
+    "role": "meta",
+    "runtime": "anthropic-api",
+    "vault_secret": "ANTHROPIC_API_KEY_HERMES",
+    "model_provider": "anthropic",
+    "default_model": "claude-opus-4-7",
+    "reports_to": None,
+    "description": (
+        "L2 autonomous companion. Reads Omega state, proposes missions, "
+        "dispatches them DOWN into AISB. Runs on its own paid Anthropic "
+        "budget — never drains Claude Max."
+    ),
+}
+
+
+# The 13-agent AISB suite — pulled from the canonical
+# bootstrap/templates/aisb/ tree. Each Paperclip agent maps 1:1 with one
+# .md persona file in that tree.
+AISB_AGENTS: list[dict[str, Any]] = [
+    {
+        "id": "niobe",
+        "title": "Niobe — AISB matriarch / intake",
+        "role": "intake",
+        "reports_to": "hermes",
+        "description": (
+            "Telegram-first classifier. Reads every inbound message, "
+            "decides Simple/Medium/Complex/Epic, dispatches to an oracle "
+            "with a structured brief."
+        ),
+    },
+    {
+        "id": "oracle",
+        "title": "Oracle — per-project planner",
+        "role": "planner",
+        "reports_to": "niobe",
+        "description": (
+            "Owns project context. Reads the brief + project CLAUDE.md, "
+            "decomposes into worker subtasks with verify_cmd, dispatches "
+            "and verifies completion."
+        ),
+    },
+    {
+        "id": "keymaker",
+        "title": "Keymaker — system planner / DAG",
+        "role": "system-planner",
+        "reports_to": "niobe",
+        "description": (
+            "Cross-project planning. Builds dependency DAGs for multi-"
+            "project missions (Genesis features, refonte programs)."
+        ),
+    },
+    {
+        "id": "construct",
+        "title": "Construct — worker executor",
+        "role": "worker",
+        "reports_to": "oracle",
+        "description": (
+            "Short-lived. Receives PLAN + FILES IN SCOPE + DONE CRITERIA + "
+            "VERIFY COMMAND. Executes step-by-step. Writes .done.json."
+        ),
+    },
+    {
+        "id": "seraph",
+        "title": "Seraph — quality gate / mission auditor",
+        "role": "auditor",
+        "reports_to": "niobe",
+        "description": (
+            "Runs 1–3 Quality Arsenal audits at close-gate. Requires "
+            "≥85/100 to approve. Falsifies before approving."
+        ),
+    },
+    {
+        "id": "smith",
+        "title": "Smith — learning + reflection",
+        "role": "educator",
+        "reports_to": "niobe",
+        "description": (
+            "Writes lessons (approved missions) + mistakes (rejected ≥2 "
+            "retries) to SQLite FTS5 memory. Next workers boot with the "
+            "5 most-recent lessons for the project."
+        ),
+    },
+    {
+        "id": "link",
+        "title": "Link — secure delivery / IO",
+        "role": "io",
+        "reports_to": "niobe",
+        "description": (
+            "Handles all outbound (Telegram, email, webhooks) + signed "
+            "inbound. HMAC verification, replay window enforcement."
+        ),
+    },
+    {
+        "id": "merovingian",
+        "title": "Merovingian — librarian / RAG",
+        "role": "librarian",
+        "reports_to": "niobe",
+        "description": (
+            "Owns the RAG corpus (hybrid + graph + agentic). Surfaces "
+            "context to other agents on demand."
+        ),
+    },
+    {
+        "id": "morpheus",
+        "title": "Morpheus — executor coordinator",
+        "role": "coordinator",
+        "reports_to": "oracle",
+        "description": (
+            "Orchestrates parallel workers. Dispatches multi-worker waves, "
+            "handles concurrency + dependencies + retry."
+        ),
+    },
+    {
+        "id": "architect",
+        "title": "Architect — system design / refactor",
+        "role": "architect",
+        "reports_to": "oracle",
+        "description": (
+            "Reads the codebase, finds entities, proposes refactors. "
+            "Owns architectural decisions, never executes them directly."
+        ),
+    },
+    {
+        "id": "neo",
+        "title": "Neo — uptime + recovery",
+        "role": "ops",
+        "reports_to": "niobe",
+        "description": (
+            "Monitors sessions, resource usage, alert thresholds. "
+            "Triggers /resurrect on stall. Never decides — just notifies."
+        ),
+    },
+    {
+        "id": "pythia",
+        "title": "Pythia — watcher / proposals (read-only)",
+        "role": "watcher",
+        "reports_to": "niobe",
+        "description": (
+            "Weekly read-only scan of platform docs + GitHub. Produces "
+            "gap-analysis proposals. Reports to Architect for triage. "
+            "NEVER touches billing/auth scopes."
+        ),
+    },
+    {
+        "id": "zion",
+        "title": "Zion — dashboard / metrics",
+        "role": "metrics",
+        "reports_to": "niobe",
+        "description": (
+            "Weekly dashboard generator. Pulls .done.json + audit history "
+            "+ session metrics. Produces formatted reports."
+        ),
+    },
+]
+
+
+def all_agents() -> list[dict[str, Any]]:
+    """Return Hermès + the 13 AISB suite — 14 agents total."""
+    return [HERMES_AGENT] + AISB_AGENTS
+
+
+# ---------------------------------------------------------------------------
+# Paperclip filesystem layout (canonical paths under PAPERCLIP_HOME)
+# ---------------------------------------------------------------------------
+
+
+def paperclip_home() -> Path:
+    """Where Paperclip stores its agent configs + DB + secrets.
+
+    Resolution order:
+      1. ``PAPERCLIP_HOME`` env var (operator override)
+      2. ``~/.paperclip``                       (typical Mac/Linux)
+      3. ``$XDG_DATA_HOME/paperclip``           (XDG-conformant Linux)
+    """
+    env = os.environ.get("PAPERCLIP_HOME")
+    if env:
+        return Path(env).expanduser()
+    home = Path.home() / ".paperclip"
+    return home
+
+
+def omegaos_company_dir(home: Path | None = None) -> Path:
+    """Where OmegaOS's company config lives under PAPERCLIP_HOME."""
+    base = home or paperclip_home()
+    return base / "companies" / "omegaos"
+
+
+# ---------------------------------------------------------------------------
+# Heartbeat sender
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Heartbeat:
+    """One heartbeat — sent from an OmegaOS tmux session to Paperclip."""
+
+    agent_id: str               # "construct" / "oracle" / "hermes" / …
+    project: str                # OmegaOS slug
+    session: str                # tmux session name
+    status: str                 # "alive" | "working" | "done_clean" | "failed"
+    summary: str = ""           # 1-line description of current work
+    timestamp: float = field(default_factory=time.time)
+    cost_so_far_usd: float = 0.0
+    omega_home: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def send_heartbeat(
+    hb: Heartbeat,
+    *,
+    paperclip_url: str = "",
+    paperclip_dir: Path | None = None,
+) -> bool:
+    """Send one heartbeat to Paperclip.
+
+    Two transport modes:
+      1. HTTP POST to ``paperclip_url + /api/heartbeat`` when configured
+      2. Filesystem drop into
+         ``$PAPERCLIP_HOME/companies/omegaos/heartbeats/<agent>-<ts>.json``
+         when there's no live Paperclip server (offline-friendly).
+
+    Returns True when the heartbeat was accepted/recorded.
+    """
+    payload = hb.to_dict()
+    if paperclip_url:
+        try:
+            import urllib.request as _urllib
+            import urllib.error as _ue
+            req = _urllib.Request(
+                f"{paperclip_url.rstrip('/')}/api/heartbeat",
+                data=json.dumps(payload).encode(),
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with _urllib.urlopen(req, timeout=5):  # noqa: S310
+                return True
+        except _ue.URLError:
+            pass
+        except Exception:  # noqa: BLE001
+            pass
+    # Filesystem fallback — Paperclip will pick these up on next boot.
+    target_dir = (paperclip_dir or omegaos_company_dir()) / "heartbeats"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    fname = f"{hb.agent_id}-{int(hb.timestamp)}-{os.getpid()}.json"
+    (target_dir / fname).write_text(json.dumps(payload, indent=2))
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Registration — write Paperclip's agent + company config from OmegaOS
+# ---------------------------------------------------------------------------
+
+
+def register(*,
+             omega_home: Path | str | None = None,
+             paperclip_dir: Path | None = None,
+             dry_run: bool = False) -> dict[str, Any]:
+    """Idempotently write Paperclip's `companies/omegaos/` tree from
+    the OmegaOS state.
+
+    Writes:
+      $PAPERCLIP_HOME/companies/omegaos/company.json     ← top-level config
+      $PAPERCLIP_HOME/companies/omegaos/agents/<id>.json ← per-agent (14 files)
+      $PAPERCLIP_HOME/companies/omegaos/workspaces/<slug>.json ← per-project
+      $PAPERCLIP_HOME/companies/omegaos/.bridge-version  ← versioning marker
+
+    Returns a summary dict for the caller (and the omega CLI).
+    """
+    home = Path(omega_home) if omega_home else Path(
+        os.environ.get("OMEGA_HOME", str(Path.home() / "Omega"))
+    )
+    pdir = paperclip_dir or omegaos_company_dir()
+    summary = {
+        "company": "omegaos",
+        "paperclip_home": str(pdir.parent.parent),
+        "company_dir": str(pdir),
+        "agents_written": 0,
+        "workspaces_written": 0,
+        "dry_run": dry_run,
+    }
+
+    agents = all_agents()
+    workspaces = _discover_projects(home)
+
+    if not dry_run:
+        pdir.mkdir(parents=True, exist_ok=True)
+        (pdir / "agents").mkdir(exist_ok=True)
+        (pdir / "workspaces").mkdir(exist_ok=True)
+        (pdir / "heartbeats").mkdir(exist_ok=True)
+
+        # company.json — the master config
+        company = {
+            "id": "omegaos",
+            "name": "Omega OS",
+            "tagline": (
+                "Verified-completion agentic operating system. "
+                "Hermès above, AISB intake, Oracle plans, Workers execute."
+            ),
+            "homepage": "https://github.com/agentik-os/OmegaOS",
+            "credential_domains": [
+                {
+                    "id": "claude-max-oauth",
+                    "label": "Claude Max OAuth (AISB+Oracle+Workers)",
+                    "source": "~/.claude/.credentials.json",
+                    "cost_per_call": 0.0,
+                    "notes": "OAuth token for Claude Code Max — covered by sub",
+                },
+                {
+                    "id": "anthropic-api-hermes",
+                    "label": "Anthropic API (Hermès only)",
+                    "vault_ref": "ANTHROPIC_API_KEY_HERMES",
+                    "notes": "Hermès's own paid budget, isolated from Max",
+                },
+            ],
+            "verified_completion": {
+                "signal": ".done.json",
+                "status_values": ["done_clean", "pending", "failed"],
+                "audit_gate": "Seraph runs 1-3 Quality Arsenal audits ≥85/100",
+            },
+            "agent_count": len(agents),
+            "workspace_count": len(workspaces),
+            "bridge_version": _bridge_version(),
+            "registered_at": time.time(),
+        }
+        (pdir / "company.json").write_text(json.dumps(company, indent=2) + "\n")
+
+        # Per-agent files
+        for agent in agents:
+            (pdir / "agents" / f"{agent['id']}.json").write_text(
+                json.dumps(agent, indent=2) + "\n"
+            )
+            summary["agents_written"] += 1
+
+        # Per-workspace (project) files
+        for ws in workspaces:
+            (pdir / "workspaces" / f"{ws['slug']}.json").write_text(
+                json.dumps(ws, indent=2) + "\n"
+            )
+            summary["workspaces_written"] += 1
+
+        # Bridge version marker
+        (pdir / ".bridge-version").write_text(_bridge_version() + "\n")
+    else:
+        summary["agents_written"] = len(agents)
+        summary["workspaces_written"] = len(workspaces)
+
+    return summary
+
+
+def _bridge_version() -> str:
+    """Pin to the OmegaOS engine version that wrote the bridge config."""
+    try:
+        from omega_engine import __version__
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+def _discover_projects(omega_home: Path) -> list[dict[str, Any]]:
+    """Walk Agentik_Coding/projects/<slug>/ and return Paperclip-shape
+    workspace dicts."""
+    projects_root = omega_home / "Agentik_Coding" / "projects"
+    out: list[dict[str, Any]] = []
+    if not projects_root.is_dir():
+        return out
+    for entry in sorted(projects_root.iterdir()):
+        if not entry.is_dir():
+            continue
+        slug = entry.name
+        project_yaml = entry / "PROJECT.yaml"
+        meta: dict[str, Any] = {"slug": slug, "path": str(entry)}
+        if project_yaml.exists():
+            try:
+                import yaml as _yaml
+                meta.update(_yaml.safe_load(project_yaml.read_text()) or {})
+            except Exception:  # noqa: BLE001
+                pass
+        # Paperclip "workspace" shape
+        out.append({
+            "id": slug,
+            "slug": slug,
+            "title": meta.get("title") or slug,
+            "phase": meta.get("phase") or "unknown",
+            "stack": meta.get("stack") or {},
+            "path": str(entry),
+            "registered_at": time.time(),
+        })
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Status — does Paperclip know about OmegaOS, and how fresh?
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BridgeStatus:
+    paperclip_installed: bool
+    paperclip_home: str
+    company_dir: str
+    company_registered: bool
+    bridge_version: str
+    omega_version: str
+    agents_registered: int
+    workspaces_registered: int
+    heartbeats_pending: int
+    drift: bool                       # bridge_version != omega_version
+
+
+def status() -> BridgeStatus:
+    """Return current bridge state — used by `omega paperclip status` +
+    `omega doctor`."""
+    pdir = omegaos_company_dir()
+    binary_present = bool(shutil.which("paperclip"))
+    bridge_v = ""
+    omega_v = _bridge_version()
+    company_present = (pdir / "company.json").exists()
+    agents_n = len(list((pdir / "agents").glob("*.json"))) if pdir.exists() else 0
+    workspaces_n = (
+        len(list((pdir / "workspaces").glob("*.json"))) if pdir.exists() else 0
+    )
+    heartbeats_n = (
+        len(list((pdir / "heartbeats").glob("*.json"))) if pdir.exists() else 0
+    )
+    if (pdir / ".bridge-version").exists():
+        bridge_v = (pdir / ".bridge-version").read_text().strip()
+    return BridgeStatus(
+        paperclip_installed=binary_present,
+        paperclip_home=str(paperclip_home()),
+        company_dir=str(pdir),
+        company_registered=company_present,
+        bridge_version=bridge_v or "(not yet registered)",
+        omega_version=omega_v,
+        agents_registered=agents_n,
+        workspaces_registered=workspaces_n,
+        heartbeats_pending=heartbeats_n,
+        drift=bool(bridge_v) and bridge_v != omega_v,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Paperclip server lifecycle (start/stop the npx onboard process)
+# ---------------------------------------------------------------------------
+
+
+def start_server(bind: str = "loopback", *, detach: bool = True) -> int:
+    """Launch the Paperclip onboard server.
+
+    bind ∈ {"loopback", "lan", "tailnet"}.
+    Returns the PID (or 0 if synchronous run requested via detach=False).
+    """
+    if not shutil.which("npx"):
+        raise RuntimeError("npx not on PATH — install Node 20+")
+    args = ["npx", "-y", "paperclipai", "onboard", "--yes"]
+    if bind == "lan":
+        args += ["--bind", "lan"]
+    elif bind == "tailnet":
+        args += ["--bind", "tailnet"]
+    if detach:
+        proc = subprocess.Popen(  # noqa: S603
+            args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        return proc.pid
+    return subprocess.call(args)

package/omega/Agentik_Engine/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "omega-engine"
-version = "0.19.32"
+version = "0.19.34"
 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_paperclip_bridge.py

@@ -0,0 +1,139 @@
+"""Regression tests for omega_engine.paperclip_bridge — locks in the
+14-agent contract and the reporting-line invariants documented in
+FEATURE-MATRIX.md §8 (AISB rules)."""
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from omega_engine import paperclip_bridge as P
+
+
+class TestAgentInventory(unittest.TestCase):
+    """Lock in the AISB contract — 14 agents total, fixed reporting."""
+
+    def test_exactly_14_agents(self):
+        """Hermès + 13 AISB suite = 14. Not 13, not 15."""
+        self.assertEqual(len(P.all_agents()), 14,
+            "the AISB contract requires exactly 14 agents — "
+            "if you added/removed one, update FEATURE-MATRIX.md §8 first")
+
+    def test_hermes_first_and_top(self):
+        agents = P.all_agents()
+        self.assertEqual(agents[0]["id"], "hermes")
+        self.assertIsNone(agents[0]["reports_to"],
+            "Hermès must be at the top of the org chart")
+
+    def test_aisb_suite_has_13(self):
+        self.assertEqual(len(P.AISB_AGENTS), 13)
+
+    def test_all_reporting_lines_valid(self):
+        """Every non-None reports_to must point to an actual agent_id."""
+        agents = P.all_agents()
+        ids = {a["id"] for a in agents}
+        for a in agents:
+            rt = a.get("reports_to")
+            if rt is not None:
+                self.assertIn(rt, ids,
+                    f"{a['id']} reports to {rt!r} which is not in the catalog")
+
+    def test_niobe_reports_to_hermes(self):
+        niobe = next(a for a in P.AISB_AGENTS if a["id"] == "niobe")
+        self.assertEqual(niobe["reports_to"], "hermes")
+
+    def test_oracle_reports_to_niobe(self):
+        oracle = next(a for a in P.AISB_AGENTS if a["id"] == "oracle")
+        self.assertEqual(oracle["reports_to"], "niobe")
+
+    def test_construct_reports_to_oracle(self):
+        c = next(a for a in P.AISB_AGENTS if a["id"] == "construct")
+        self.assertEqual(c["reports_to"], "oracle")
+
+
+class TestCredentialIsolation(unittest.TestCase):
+    """L0-L5 credential domains must not bleed. Specifically:
+       - Hermès uses ANTHROPIC_API_KEY_HERMES (vault)
+       - The 13 AISB agents must NOT declare any Anthropic API key
+         (they share Claude Max OAuth from ~/.claude/.credentials.json)."""
+
+    def test_hermes_uses_anthropic_key(self):
+        self.assertEqual(P.HERMES_AGENT["vault_secret"],
+                         "ANTHROPIC_API_KEY_HERMES")
+        self.assertEqual(P.HERMES_AGENT["runtime"], "anthropic-api")
+
+    def test_aisb_agents_do_not_declare_api_keys(self):
+        for a in P.AISB_AGENTS:
+            self.assertNotIn("vault_secret", a,
+                f"{a['id']} must not declare its own API key — AISB+Oracle+"
+                "Workers share the Claude Max OAuth at the engine level")
+            self.assertNotIn("runtime", a,
+                f"{a['id']} must not declare a runtime — runs as a "
+                "Claude Code subprocess under Max OAuth")
+
+
+class TestRegisterDryRun(unittest.TestCase):
+    """The register() entry point — dry-run mode must report what it
+    would write without touching disk."""
+
+    def test_dry_run_writes_nothing_to_disk(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            pdir = Path(tmp) / "companies" / "omegaos"
+            summary = P.register(paperclip_dir=pdir, dry_run=True)
+            self.assertFalse(pdir.exists(),
+                "dry_run=True must not create the company dir")
+            self.assertEqual(summary["agents_written"], 14)
+
+    def test_register_writes_14_agent_files(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            pdir = Path(tmp) / "companies" / "omegaos"
+            summary = P.register(paperclip_dir=pdir, dry_run=False)
+            # company.json
+            self.assertTrue((pdir / "company.json").exists())
+            company = json.loads((pdir / "company.json").read_text())
+            self.assertEqual(company["id"], "omegaos")
+            self.assertEqual(company["agent_count"], 14)
+            # 14 agent files
+            agent_files = list((pdir / "agents").glob("*.json"))
+            self.assertEqual(len(agent_files), 14,
+                f"register must write 14 agent files (got {len(agent_files)})")
+            # .bridge-version
+            self.assertTrue((pdir / ".bridge-version").exists())
+            self.assertEqual(summary["agents_written"], 14)
+
+
+class TestHeartbeat(unittest.TestCase):
+    """Heartbeat must drop a JSON file when no HTTP server is configured."""
+
+    def test_filesystem_fallback_writes_heartbeat(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            pdir = Path(tmp) / "companies" / "omegaos"
+            hb = P.Heartbeat(
+                agent_id="construct",
+                project="test-project",
+                session="test-session",
+                status="working",
+                summary="step 2/5 in progress",
+            )
+            ok = P.send_heartbeat(hb, paperclip_dir=pdir)
+            self.assertTrue(ok)
+            files = list((pdir / "heartbeats").glob("construct-*.json"))
+            self.assertEqual(len(files), 1)
+            payload = json.loads(files[0].read_text())
+            self.assertEqual(payload["agent_id"], "construct")
+            self.assertEqual(payload["status"], "working")
+
+
+class TestStatus(unittest.TestCase):
+    """status() must work even when nothing is registered yet."""
+
+    def test_status_safe_on_fresh_machine(self):
+        # Just call it — should not raise even if PAPERCLIP_HOME is bare.
+        st = P.status()
+        self.assertIsNotNone(st)
+        self.assertEqual(st.omega_version, P._bridge_version())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/omega/Agentik_SSOT/VERSION

@@ -1 +1 @@
-0.19.32
+0.19.34

package/omega/Agentik_SSOT/docs/AUDIT-V0.19.34.md

@@ -0,0 +1,143 @@
+# OmegaOS v0.19.34 — deep audit, all bugs & incoherences logged
+
+> Run on 2026-05-25 after the v0.19.33 Paperclip bridge ship.
+> Method: parallel checks (pytest, shell syntax, imports, parsers,
+> duplicate scan, version cross-ref, catalog parse, bridge invariants).
+
+## 1. Clean (passed)
+
+| Check | Result |
+|---|---|
+| pytest full suite | **612 passed** (599 + 13 new bridge tests) |
+| Shell syntax `install.sh + common.sh + steps.sh` | ✓ |
+| 14 internal Python modules importable | ✓ |
+| Version coherent: `__init__.py / pyproject.toml / package.json / VERSION` | 0.19.34 |
+| 4 catalog YAMLs parse cleanly | mcp 16 / plugins 11 / clis 28 / providers 16 |
+| 49 omega subcommands registered in argparse | ✓ |
+| tmux config 3-char hex regression | 0 occurrences (v0.19.28 fix holds) |
+| Paperclip bridge: 14 agents, hermes top, reporting lines | ✓ |
+| Personas: all 8 LLM filenames written by `write_all_personas` | ✓ |
+| Hermès credential isolation (ANTHROPIC_API_KEY_HERMES) | ✓ |
+| Filesystem fallback heartbeat | ✓ |
+
+## 2. Bugs found + fixed in v0.19.34
+
+| # | Bug | Severity | Fix |
+|---|---|---|---|
+| 1 | `LAYERS.md` didn't mention Paperclip even though the bridge shipped in v0.19.33 | doc gap | Added a v0.19.33+ section at the top with the L0 Paperclip diagram + pointer to FEATURE-MATRIX.md |
+| 2 | No regression tests for `paperclip_bridge` — bridge invariants (14 agents, reporting lines, credential isolation) lived only in code | test gap | Added `tests/test_paperclip_bridge.py` (13 tests, all passing) covering: agent inventory, reporting lines per agent, credential isolation (AISB must NOT declare API keys), dry-run safety, register writes 14 files, heartbeat filesystem fallback, status() on fresh machine |
+
+## 3. Code smells (NOT runtime bugs — flagged for future cleanup)
+
+### 3.1 `_omega_home` duplicated 10× across modules
+
+```
+audit_gate.py         def _omega_home() -> Path
+handoff.py            def _omega_home(home: str | Path | None) -> Path
+tools.py              def _omega_home(explicit: str | Path | None = None) -> Path
+plan.py               def _omega_home(explicit: str | Path | None = None) -> Path
+aisb_chat.py          def _omega_home() -> Path
+hermes_bootstrap.py   def _omega_home(explicit: str | Path | None) -> Path
+mission.py            def _omega_home(explicit: str | Path | None = None) -> Path
+cleanup.py            def _omega_home(home: str | Path | None) -> Path
+project.py            def _omega_home(explicit: str | Path | None = None) -> Path
+daemons/telegram.py   def _omega_home() -> Path
+```
+
+**Status**: not a runtime bug. Each module uses its own private helper.
+But **3 different signatures** for the same conceptual function is
+code smell. Refactor: extract to `omega_engine.paths.omega_home(explicit=None)`
+and update all 10 call sites. Scope: ~30 line diff, low risk. **Backlog v0.20.x.**
+
+### 3.2 `step_mcp` legacy function unreferenced from STEPS
+
+`bootstrap/lib/steps.sh` defines 22 step functions but `install.sh` only
+references 21 in its STEPS array. The orphan is `step_mcp` (deliberately
+retired in v0.19.21 when we switched to `step_clis`).
+
+**Status**: not a bug. `step_mcp` is still reachable via `omega tool install <id>`
+as a manual escape hatch. Function header documents this. **Leave as-is.**
+
+### 3.3 `cmd_billing` overlaps with `cmd_account*`
+
+There's a `cmd_billing` (since pre-v0.19) showing per-account cost
+aggregation, and a `cmd_account` family (list / login / use / pool) for
+account management. User mentioned earlier wanting `/billing` renamed to
+`/account` for Telegram parity, but the CLI subcommand is named `omega
+billing` and that's its purpose (cost surfacing).
+
+**Status**: not a bug. They serve adjacent purposes. The Telegram side
+already uses `/account` (per v0.19.x routing). CLI rename would be a
+breaking change for any user/script depending on `omega billing`.
+**Backlog**: alias `omega billing` ↔ `omega account costs`. v0.19.35+
+
+### 3.4 Multiple `_atomic_write`, `_have`, `_cache_path` helpers
+
+Same pattern as `_omega_home` — local helpers duplicated across modules
+because there's no shared `omega_engine.paths` / `omega_engine.utils`.
+Same refactor as 3.1. **Backlog v0.20.x.**
+
+## 4. Architecture invariants verified
+
+These come from FEATURE-MATRIX.md §8 (AISB rules). Audit confirms each
+is enforced AT CODE LEVEL, not just at doc level:
+
+| Invariant | Where it's enforced |
+|---|---|
+| Exactly 14 agents (Hermès + 13 AISB) | `paperclip_bridge.AISB_AGENTS` (13) + `HERMES_AGENT` (1); locked by `test_exactly_14_agents` |
+| Hermès reports to no-one | `HERMES_AGENT["reports_to"] = None`; locked by `test_hermes_first_and_top` |
+| Niobe reports to Hermès | Catalog + `test_niobe_reports_to_hermes` |
+| Oracle reports to Niobe | Catalog + `test_oracle_reports_to_niobe` |
+| Construct reports to Oracle | Catalog + `test_construct_reports_to_oracle` |
+| Credential domain isolation | `test_aisb_agents_do_not_declare_api_keys` + `test_hermes_uses_anthropic_key` |
+| `.done.json` verified completion | `done_signal.py` write_done() schema |
+| Audit gate ≥85/100 | `audit_gate.py` threshold |
+| Plan first (Oracle writes plan.md before dispatch) | Mission envelope builder + `plan.py` FSM |
+
+## 5. Counts (the system's "shape")
+
+- **Engine modules**: 60 Python files
+- **AISB suite agent prompts**: 15 .md (13 personas + CLAUDE.md + lmc-protocol.md, + protocols/ + checkers/)
+- **Test files**: 42 (was 41 — added `test_paperclip_bridge.py`)
+- **pytest tests**: 612 (was 599 — added 13)
+- **Install steps**: 21 in install.sh STEPS array
+- **Step functions defined**: 22 in steps.sh (1 legacy: step_mcp)
+- **CLI subcommands**: 49 distinct omega subcommands
+- **MCP catalog entries**: 16 (legacy, opt-in only)
+- **Claude plugins**: 11 (after v0.19.20 cleanup, claude-mem now opt-in)
+- **System CLIs**: 28 (incl. CloakBrowser, Scrapling, Paperclip, …)
+- **LLM providers**: 16 (Anthropic/OpenAI/Google/GLM/DeepSeek/Qwen/Ollama/LM Studio/OpenRouter/Bedrock/Mistral/xAI/Vercel Gateway/Copilot/OpenAI-compat/ChatGPT)
+- **Genesis stack presets**: 8 (canonical/mobile-native/mobile-expo/desktop-tauri/supabase/claude-dashboard/convex-selfhosted/sqlite-local)
+- **Personas supported**: 10 LLM filenames
+- **Quality Arsenal audits**: 17 (Skills as forensic protocols)
+
+## 6. Verdict
+
+**v0.19.34 is clean** for what it claims to do:
+
+- ✓ Multi-LLM ecosystem (13 CLIs + 16 providers + persona system)
+- ✓ Multi-scraper (CloakBrowser + Scrapling)
+- ✓ Tmux-based session orchestration (Omega master + chat windows)
+- ✓ Paperclip bridge (governance roof, 14 agents, idempotent)
+- ✓ Hermès isolated credentials (Anthropic API)
+- ✓ AISB+Oracle+Workers on Max OAuth
+- ✓ Verified completion (.done.json + audit gate)
+- ✓ Light Claude theme (fzf + tmux)
+- ✓ Arrow-key menu (fzf) + session switcher (Option+/)
+- ✓ 612 tests pass
+
+**Not yet there** (backlog v0.19.35+):
+
+- Auto-heartbeat hook in `tmux.spawn_worker / spawn_oracle`
+- Per-agent budget enforcement from Paperclip
+- HTTP heartbeat transport (currently filesystem only)
+- Refactor `_omega_home` + 4-5 other helpers into `omega_engine.paths`
+- Streaming async in the Textual TUI
+
+**Production-ready** for: distribution via npm, end-to-end install on
+macOS/Linux, multi-LLM coding sessions, project genesis, audit-gated
+missions, optional Paperclip governance.
+
+---
+
+*Audit run on commit after v0.19.33 ship, before v0.19.34 release.*

package/omega/Agentik_SSOT/docs/FEATURE-MATRIX.md

@@ -0,0 +1,193 @@
+# OmegaOS × Paperclip Feature Matrix (v0.19.33)
+
+> Cross-reference between OmegaOS (engine + AISB suite + tooling) and
+> Paperclip (governance + org-chart + UI). Identifies what each system
+> uniquely brings, where they overlap, and what the bridge fills in.
+
+---
+
+## 1. Paperclip — feature inventory
+
+| # | Feature | What it does | Maps to OmegaOS as |
+|---|---|---|---|
+| 1 | **Org chart & agents** | Roles, titles, reporting lines, JDs | OmegaOS hierarchy (Hermès / AISB suite) registered as Paperclip agents via `omega paperclip register` |
+| 2 | **Issue-based tasks** | Atomic checkout, dependencies, comments, audit logs | OmegaOS missions (`omega run`) + `.done.json` events |
+| 3 | **Heartbeat execution** | Scheduled wakeups, budget checks, secret injection | `omega paperclip heartbeat --agent-id <…>` from tmux sessions |
+| 4 | **Goal alignment** | Task → project → company → mission | OmegaOS Genesis project YAML carries `purpose` field |
+| 5 | **Budget & cost** | Token/USD per agent/provider/model, hard stops | Per-LLM-provider tracking (claude_code = $0 OAuth; hermes = paid Anthropic; OpenRouter = OpenRouter API) |
+| 6 | **Governance / approvals** | Board review, pause/terminate, config versioning | Maps to Stop-hook audit gate (Seraph ≥85/100 score) |
+| 7 | **Workspaces** | Project workspaces, git worktrees, dev servers | OmegaOS `Agentik_Coding/projects/<slug>/` per-project isolation |
+| 8 | **Routines / schedules** | Cron, webhook, API triggers | OmegaOS autonomous charters in `Agentik_Orchestration/autonomous/` |
+| 9 | **Plugin system** | Instance-wide extensibility | OmegaOS skill catalog (`Agentik_SSOT/skills/`) |
+| 10 | **Secrets storage** | Encrypted local + provider-backed | OmegaOS age vault (`omega vault`) |
+| 11 | **Activity events** | Durable audit log | OmegaOS `Agentik_Runtime/eventlog/omega.db` |
+| 12 | **Company portability** | Export/import org with secret scrubbing | OmegaOS Genesis pipeline + manifest YAML |
+| 13 | **Multi-company support** | One deployment, many tenants | Multi-project under one `~/Omega` |
+| 14 | **Mobile-ready management** | Browser UI for phones | OmegaOS Telegram bot (less rich but works) |
+| 15 | **Web dashboard (React)** | Visual governance UI | Not in OmegaOS — fixed by registering OmegaOS as a Paperclip company |
+| 16 | **PostgreSQL backend** | Production DB | OmegaOS uses SQLite WAL per project (simpler but smaller scale) |
+
+---
+
+## 2. OmegaOS — feature inventory
+
+| # | Feature | What it does | Maps to Paperclip as |
+|---|---|---|---|
+| 1 | **AISB suite (13 agents)** | Niobe/Oracle/Construct/Seraph/Smith/… | 13 agent rows in Paperclip's org chart |
+| 2 | **Hermès L2** | Meta-companion on Anthropic API | Top-of-chart "COO" agent in Paperclip (own credential domain) |
+| 3 | **Genesis project pipeline** | vision→market→branding→PRD→features→plan | Workspace template in Paperclip |
+| 4 | **Verified completion (`.done.json`)** | Worker status signal | Issue completion event with payload |
+| 5 | **17 Quality Arsenal audits** | Forensic Gestalt-Popper audits | Approval workflow stages |
+| 6 | **Plan v7 FSM-enforced executor** | Multi-day autonomous loop | Routines with state machine |
+| 7 | **Claude Code Max OAuth** | Free-with-sub credential | Provider config (credential domain 1) |
+| 8 | **Hermès Anthropic API key** | Isolated paid budget | Provider config (credential domain 2) |
+| 9 | **13 LLM CLIs + hot-swap** | Claude/Gemini/Codex/OpenCode/Qwen/… | Agent runtime flexibility (each agent picks its CLI) |
+| 10 | **16 provider configs** | Anthropic/OpenAI/Google/GLM/DeepSeek/Qwen/Ollama/LM Studio/OpenRouter/Bedrock/Mistral/xAI/Vercel Gateway/Copilot | Multi-provider routing |
+| 11 | **Persona system** | 1 canonical → 10 LLM filenames | Agent prompt portability |
+| 12 | **CloakBrowser scraper** | Stealth web scraping | Available to all Paperclip agents via `omega scrape` |
+| 13 | **Scrapling scraper** | Fast HTTP-first scraping | Same |
+| 14 | **Printing Press CLIs** | Agent-native CLIs (Stripe, Linear, …) | Same — available to all agents |
+| 15 | **Tmux session orchestration** | Persistent sessions for oracles/workers | Workspace runtime backing |
+| 16 | **`omega` TUI** | fzf arrow menu + slash REPL | Terminal-side control surface |
+| 17 | **Telegram bot (AISB)** | Intake + dispatch | Mobile management surface |
+| 18 | **age-encrypted vault** | Secrets storage | Maps to Paperclip's secrets store |
+| 19 | **Autonomous charters** | Cron-driven agent triggers | Paperclip routines |
+| 20 | **Event-sourced FSM** | Per-task state machine | Issue lifecycle in Paperclip |
+| 21 | **`omega switch`** | Hot-swap LLM provider | Per-agent runtime change |
+| 22 | **`omega scrape`** | Unified scraper interface | Tool surface for all agents |
+| 23 | **`omega doctor`** | 30+ health checks | Paperclip dashboard's health view |
+| 24 | **599 pytest tests** | Engine correctness | (Paperclip has its own test suite) |
+| 25 | **Distributable via npm** | `npx @agentikos/omega-os@latest` | Single npm package, multi-platform |
+
+---
+
+## 3. Merger — the bridge fills these gaps
+
+What OmegaOS WAS MISSING and Paperclip provides:
+
+| OmegaOS gap | Paperclip fills it |
+|---|---|
+| No visual dashboard | Paperclip's React UI surfaces all 14 agents + projects + missions |
+| Per-agent budget enforcement | Paperclip's budget engine (we report; Paperclip enforces) |
+| Cross-LLM cost transparency | Paperclip's per-provider token tracking |
+| Board-level approvals (beyond audit gate) | Paperclip's approval workflows |
+| Company portability with secret scrubbing | Paperclip's export/import |
+
+What Paperclip WAS MISSING and OmegaOS provides:
+
+| Paperclip gap | OmegaOS fills it |
+|---|---|
+| 13 AISB agent personas | Paperclip company "omegaos" auto-registers them via bridge |
+| Hermès L2 meta-companion | New agent role in Paperclip's chart |
+| Verified-completion contract | OmegaOS's `.done.json` → Paperclip issue close event |
+| Quality Arsenal audits (17 forensic) | Available to all Paperclip agents via `omega audit <id>` |
+| Stealth scraping (CloakBrowser + Scrapling) | Available via `omega scrape <url>` |
+| Hot-swap LLM mid-flight | `omega switch` from any Paperclip agent's runtime |
+| Genesis project pipeline | Stack-aware workspace bootstrap |
+| Age-encrypted vault | More secure than Paperclip's bare encrypted-local |
+| 21-step installer with plan mode | One-line distribution beyond Paperclip's `npx onboard` |
+
+---
+
+## 4. Bridge layer (v0.19.33 ship)
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  PAPERCLIP — L0 governance (React UI, web dashboard)             │
+│  $PAPERCLIP_HOME/companies/omegaos/                              │
+│    ├── company.json          ← OmegaOS company config            │
+│    ├── agents/<id>.json      ← 14 agent profiles                 │
+│    ├── workspaces/<slug>.json ← per-Genesis-project workspace    │
+│    └── heartbeats/*.json     ← live status from tmux sessions    │
+└────────────────────────────────┬─────────────────────────────────┘
+                                 │
+                       OmegaOS engine writes here via:
+                       `omega paperclip register`
+                       `omega paperclip sync`
+                       `omega paperclip heartbeat`
+                                 │
+┌────────────────────────────────▼─────────────────────────────────┐
+│  OMEGAOS — L1-L5 execution                                       │
+│  Hermès (L2) → AISB (L3) → Oracle (L4) → Workers (L5)            │
+│  Engine: ~/Omega/Agentik_Engine/omega_engine/                    │
+│  State:  ~/Omega/Agentik_Runtime/                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## 5. Bridge commands (v0.19.33)
+
+| Command | Effect |
+|---|---|
+| `omega paperclip status` | Show bridge health (agents/workspaces/heartbeats count, version drift) |
+| `omega paperclip register` | Write Paperclip company config (idempotent) |
+| `omega paperclip register --dry-run` | Preview without writing |
+| `omega paperclip start [--bind loopback\|lan\|tailnet]` | Launch Paperclip server via `npx onboard` |
+| `omega paperclip heartbeat --agent-id <id> --status <s>` | Send heartbeat from any tmux session |
+
+## 6. Features added to OmegaOS in v0.19.33
+
+1. `omega_engine.paperclip_bridge` module (this file).
+2. `omega paperclip` CLI subcommand (4 verbs).
+3. Per-agent profiles for the 13 AISB suite + Hermès, ready to be
+   written into Paperclip's `companies/omegaos/agents/` directory.
+4. Workspace discovery — reads `Agentik_Coding/projects/<slug>/PROJECT.yaml`,
+   maps each to a Paperclip workspace.
+
+## 7. Features still to add (v0.19.34+)
+
+1. **Heartbeat sender wired into spawn**: `tmux.spawn_worker()` and
+   `tmux.spawn_oracle()` should auto-call `omega paperclip heartbeat
+   --agent-id <id> --status alive` on spawn + on exit.
+2. **Per-agent budget enforcement in OmegaOS** mirroring Paperclip's
+   limits — read the budget config back from Paperclip and refuse new
+   missions when over budget.
+3. **Genesis stack option: "paperclip-managed"** — generates a
+   Paperclip company.json at project creation time alongside PROJECT.yaml.
+4. **`omega paperclip import <export.tar.gz>`** — adopt an OmegaOS
+   project from a Paperclip company export.
+5. **Heartbeat HTTP transport** — currently writes JSON to disk
+   (filesystem fallback). Add live POST to a running Paperclip server
+   when the URL is set.
+6. **AISB suite registration depth**: per-agent skills/tools mapping
+   so Paperclip's dashboard shows which Quality Arsenal audits Seraph
+   owns, which providers Hermès uses, etc.
+
+---
+
+## 8. AISB rules enforced across both systems
+
+These are non-negotiable contracts that both OmegaOS code AND
+Paperclip config must respect:
+
+1. **14 agents total** (Hermès + 13 AISB suite). The bridge writes
+   exactly 14 agent profiles — no more, no less.
+2. **Reporting lines fixed**:
+   - Hermès reports to nobody (top)
+   - Niobe reports to Hermès (intake matriarch)
+   - Oracle/Keymaker/Seraph/Smith/Link/Merovingian/Neo/Pythia/Zion
+     report to Niobe (specialists)
+   - Construct/Morpheus/Architect report to Oracle (per-project execution)
+3. **Credential domain isolation**:
+   - Claude Max OAuth → AISB+Oracle+Workers only (L3-L5)
+   - Anthropic API → Hermès only (L2)
+   - Paperclip never sees the live tokens, only credential domain refs
+4. **Verified completion contract**:
+   - Every Worker writes `.done.json` with `status ∈ {done_clean, pending, failed}`
+   - Oracle waits for ALL its workers' `.done.json` before its own
+   - Seraph runs 1-3 Quality Arsenal audits with score ≥85/100 to approve
+   - Paperclip's issue close event mirrors this state
+5. **Plans are first-class**:
+   - Oracle writes `plan.md` in `/project/<slug>/` before dispatching
+   - Workers receive PLAN + FILES IN SCOPE + DONE CRITERIA + VERIFY COMMAND
+   - Plan deviation = audit gate FAIL
+
+These rules are baked into:
+- `omega_engine.envelope` (mission envelope builder)
+- `omega_engine.audit_arsenal` (audit gate)
+- `omega_engine.paperclip_bridge.AISB_AGENTS` (this file's catalog)
+- `Agentik_SSOT/agents/aisb/CLAUDE.md` (master prompt)
+- `Agentik_SSOT/personas/OMEGAOS-CONTEXT.md` (per-LLM context)
+
+---
+
+*Audit produit pour v0.19.33 — 2026-05-25.*

package/omega/Agentik_SSOT/docs/LAYERS.md

@@ -1,9 +1,28 @@
 # OmegaOS Layered Architecture
 
-> Five layers. **Two independent credential domains.** **Two Telegram bots
-> with separate tokens.** Hermès sits above; AISB+Oracle+Workers stay below.
+> **Six layers** (L0–L5) with Paperclip as the optional governance roof.
+> Two independent credential domains. Two Telegram bots with separate
+> tokens. Hermès above the OmegaOS core; AISB+Oracle+Workers below.
 > Each layer is independently usable.
 
+## v0.19.33+ — Paperclip as L0 governance
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Layer 0 ─ PAPERCLIP (optional, governance roof)                     │
+│  React dashboard + budget + org chart + approvals.                   │
+│  Registered via `omega paperclip register` — writes                  │
+│  ~/.paperclip/companies/omegaos/ with 14 agent profiles.             │
+│  Heartbeats from L1-L5 sessions feed this layer.                     │
+└────────────────────────────────────────┬─────────────────────────────┘
+                                         │
+                                         ▼
+[everything below is the original L1-L5 model]
+```
+
+See `omega/Agentik_SSOT/docs/FEATURE-MATRIX.md` for the full feature
+cross-reference + bridge command list.
+
 ## The corrected model (v0.19.14)
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentikos/omega-os",
-  "version": "0.19.32",
+  "version": "0.19.34",
   "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"