mishkan-harness 0.2.0 → 0.2.4

package/payload/mishkan/observability/watch/src/mishkan_watch/__main__.py

@@ -1,24 +1,106 @@
-"""mishkan-watch CLI entry point."""
+"""mishkan-watch CLI entry point.
+
+UX contract: ``mishkan-watch`` is a single command. If the daemon isn't
+already running we fork it as a child process, wait briefly for its
+socket to appear, then launch the TUI. On TUI exit we leave the daemon
+alive so other clients (a second ``mishkan-watch`` window, the TUI on
+another tmux pane) can use it. ``mishkan-watchd stop`` remains the
+explicit shutdown.
+
+The dual-terminal flow (one for ``mishkan-watchd start``, one for the
+TUI) still works for power users — pass ``--no-autostart`` and the
+client refuses to manage the daemon.
+"""
 from __future__ import annotations
 
 import argparse
 import os
+import shutil
+import subprocess
 import sys
+import time
 from pathlib import Path
 
 
 DEFAULT_SOCKET = Path(os.path.expanduser("~/.claude/mishkan/run/watch.sock"))
+WATCHD_BOOT_TIMEOUT_S = 8.0
+WATCHD_BOOT_POLL_MS = 100
+
+
+def _ensure_daemon(socket_path: Path, *, allow_autostart: bool) -> int:
+    """Return 0 on success, 1 on failure.
+
+    If the socket already exists we assume the daemon is up — this is
+    the common case (daemon already running across sessions). Otherwise,
+    when autostart is allowed and ``mishkan-watchd`` is on PATH, we
+    fork it and poll for the socket up to WATCHD_BOOT_TIMEOUT_S.
+    """
+    if socket_path.exists():
+        return 0
+    if not allow_autostart:
+        print(
+            "mishkan-watch: daemon socket not found and --no-autostart was "
+            "passed.\n  Start the daemon manually:  mishkan-watchd start",
+            file=sys.stderr,
+        )
+        return 1
+    watchd = shutil.which("mishkan-watchd")
+    if not watchd:
+        print(
+            "mishkan-watch: daemon socket not found and `mishkan-watchd` is "
+            "not on PATH.\n  Install the observability stack:\n"
+            "    npx mishkan-harness observability",
+            file=sys.stderr,
+        )
+        return 1
+    print("mishkan-watch: starting daemon …", file=sys.stderr)
+    # Detached child — survives this process. stdout/stderr go to /dev/null
+    # so the TUI doesn't get polluted by daemon log lines.
+    try:
+        subprocess.Popen(
+            [watchd, "start"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+            close_fds=True,
+        )
+    except OSError as e:
+        print(f"mishkan-watch: failed to fork daemon: {e}", file=sys.stderr)
+        return 1
+    # Poll for socket. Bounded; the daemon binds the socket within the
+    # first ~200 ms in normal conditions, but uv tool first runs and
+    # cold imports can push it higher on slow disks.
+    deadline = time.monotonic() + WATCHD_BOOT_TIMEOUT_S
+    while time.monotonic() < deadline:
+        if socket_path.exists():
+            return 0
+        time.sleep(WATCHD_BOOT_POLL_MS / 1000)
+    print(
+        f"mishkan-watch: daemon socket {socket_path} did not appear within "
+        f"{WATCHD_BOOT_TIMEOUT_S:.0f} s.\n  Check daemon logs:  "
+        "mishkan-watchd status",
+        file=sys.stderr,
+    )
+    return 1
 
 
 def cli(argv: list[str] | None = None) -> int:
     p = argparse.ArgumentParser(
         prog="mishkan-watch",
-        description="MISHKAN observability TUI. Connects to mishkan-watchd.",
+        description="MISHKAN observability TUI. Auto-starts the daemon "
+                    "if it isn't running.",
     )
     p.add_argument("--socket", type=Path, default=DEFAULT_SOCKET,
                    help=f"daemon UNIX socket (default: {DEFAULT_SOCKET})")
+    p.add_argument("--no-autostart", action="store_true",
+                   help="don't fork the daemon; refuse if socket missing")
     args = p.parse_args(argv)
 
+    rc = _ensure_daemon(args.socket, allow_autostart=not args.no_autostart)
+    if rc != 0:
+        return rc
+
     # Importing the app lazily keeps CLI startup fast even when Textual is
     # heavy to import.
     from .app import run

package/payload/mishkan/observability/watch/src/mishkan_watch/app.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import os
 import time
 from pathlib import Path
+
 from typing import Any
 
 from textual import work
@@ -24,6 +25,9 @@ from .tabs.activity import ActivityTab
 from .tabs.agents import AgentsTab
 from .tabs.knowledge import KnowledgeTab
 from .tabs.live import LiveTab
+from .tabs.org import OrgTab
+from .tabs.skills import SkillsTab
+from .tabs.usage import UsageTab
 from .tabs.workflows import WorkflowsTab
 
 
@@ -40,6 +44,10 @@ class MishkanWatch(App):
         Binding("3", "switch_tab('workflows')", "Workflows"),
         Binding("4", "switch_tab('knowledge')", "Knowledge"),
         Binding("5", "switch_tab('activity')", "Activity"),
+        Binding("6", "switch_tab('org-ref')", "Org-Ref"),
+        Binding("7", "switch_tab('usage')", "Usage"),
+        Binding("8", "switch_tab('skills')", "Skills"),
+        Binding("p", "toggle_project_filter", "Project/All"),
         Binding("question_mark", "show_help", "help", show=False),
     ]
 
@@ -48,6 +56,17 @@ class MishkanWatch(App):
         self._socket_path = socket_path or DEFAULT_SOCKET
         self._client: DaemonClient | None = None
         self._started_at = time.time()
+        # Project filter — at startup, prefer CLAUDE_PROJECT_DIR (set by
+        # Claude Code in subprocess hooks), fall back to cwd. None means
+        # "show all projects" (toggle via 'p' key).
+        self._current_project: Path = Path(
+            os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+        ).resolve()
+        # Default OFF — the filter is opt-in via 'p'. Defaulting ON broke
+        # rendering for users whose sess.project carries the Claude Code
+        # encoded form (e.g. -home-ogu-theY4NN-harness) instead of an
+        # absolute path; the comparator below tolerates both forms.
+        self._filter_to_current: bool = False
         self._totals = {
             "tokens_in": 0,
             "tokens_out": 0,
@@ -72,8 +91,26 @@ class MishkanWatch(App):
                 yield KnowledgeTab(id="tab-knowledge")
             with TabPane("Activity", id="activity"):
                 yield ActivityTab(id="tab-activity")
-        yield Static("", id="status-bar")
+            with TabPane("Org-Ref", id="org-ref"):
+                yield OrgTab(id="tab-org-ref")
+            with TabPane("Usage", id="usage"):
+                yield UsageTab(id="tab-usage")
+            with TabPane("Skills", id="skills"):
+                yield SkillsTab(id="tab-skills")
+        # Footer docked first so it lands at the very bottom; status-bar
+        # yielded after so it sits just above. Otherwise both compete for
+        # the same bottom slot and Footer wins (status-bar invisible).
         yield Footer()
+        yield Static("", id="status-bar")
+
+    def on_mount_initial_filter(self) -> None:
+        """Propagate the initial project filter to tabs that support it."""
+        for tab in self._all_tabs():
+            try:
+                if hasattr(tab, "set_project_filter") and self._filter_to_current:
+                    tab.set_project_filter(self._current_project)
+            except Exception:
+                continue
 
     async def on_mount(self) -> None:
         # Status bar refresh on a fixed cadence rather than on every event.
@@ -81,6 +118,7 @@ class MishkanWatch(App):
         # on each was a major source of UI latency. 500 ms ticks feel
         # live without saturating the loop.
         self.set_interval(0.5, self._refresh_status_bar)
+        self.on_mount_initial_filter()
         self._client = DaemonClient(self._socket_path)
         await self._client.start(self._on_frame, self._on_status)
 
@@ -129,7 +167,7 @@ class MishkanWatch(App):
 
     def _all_tabs(self) -> list[Any]:
         out = []
-        for sel in ("#tab-live", "#tab-agents", "#tab-workflows", "#tab-knowledge", "#tab-activity"):
+        for sel in ("#tab-live", "#tab-agents", "#tab-workflows", "#tab-knowledge", "#tab-activity", "#tab-org-ref", "#tab-usage", "#tab-skills"):
             try:
                 out.append(self.query_one(sel))
             except Exception:
@@ -222,12 +260,35 @@ class MishkanWatch(App):
         # Minimal help; expand into a modal in a follow-up.
         try:
             bar = self.query_one("#status-bar", Static)
-            help_text = Text("1-5 tabs · / filter (Activity) · q quit",
+            help_text = Text("1-8 tabs · p project filter · / filter (Activity) · q quit",
                              style="bold")
             bar.update(help_text)
         except Exception:
             pass
 
+    def action_toggle_project_filter(self) -> None:
+        """Toggle between 'current project only' and 'all projects' filter.
+
+        Live tab reads `app.filter_project` to decide what to show. When
+        the filter is on, only sessions/worktrees whose project path
+        matches `self._current_project` are rendered.
+        """
+        self._filter_to_current = not self._filter_to_current
+        # Force a re-render of the structural panels via a fake snapshot pass.
+        for tab in self._all_tabs():
+            try:
+                if hasattr(tab, "set_project_filter"):
+                    tab.set_project_filter(
+                        self._current_project if self._filter_to_current else None
+                    )
+            except Exception:
+                continue
+        self._refresh_status_bar()
+
+    @property
+    def filter_project(self) -> Path | None:
+        return self._current_project if self._filter_to_current else None
+
 
 def run(socket_path: Path | None = None) -> int:
     app = MishkanWatch(socket_path=socket_path)

package/payload/mishkan/observability/watch/src/mishkan_watch/org_data.py

@@ -0,0 +1,79 @@
+"""Shared loader for the MISHKAN org.json reference.
+
+Used by:
+  - tabs/org.py     : full org tree + details panel
+  - tabs/agents.py  : inline role annotation next to alias
+  - tabs/live.py    : same
+
+Loads once at import; refreshes are cheap (re-call _load_org()).
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def _candidate_paths() -> list[Path]:
+    """Where org.json may live, first hit wins.
+
+    Order matters: the installed (~/.claude) copy is canonical because
+    it tracks the harness version actually in use. Repo fallbacks are
+    for dev mode (running mishkan-watch out of the source checkout).
+    """
+    paths: list[Path] = [
+        Path(os.path.expanduser("~/.claude/mishkan/org/org.json")),
+    ]
+    # Walk up from this file looking for `payload/mishkan/org/org.json`
+    # in case we're running from the repo checkout (dev mode).
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "payload" / "mishkan" / "org" / "org.json"
+        if candidate.is_file():
+            paths.append(candidate)
+            break
+        if parent == parent.parent:
+            break
+    return paths
+
+
+def load_org() -> dict[str, Any]:
+    for p in _candidate_paths():
+        try:
+            if p.is_file():
+                return json.loads(p.read_text())
+        except Exception:
+            continue
+    return {"groups": []}
+
+
+def role_for(alias: str, org: dict[str, Any] | None = None) -> str | None:
+    """Return the snake_case role for a given alias, or None if unknown.
+
+    alias matching is case-insensitive. Returns the `short` field if
+    present (e.g. "PM"), else the full `role` (e.g. "project_manager").
+    The caller chooses which form to render.
+    """
+    if not alias:
+        return None
+    org = org or load_org()
+    key = alias.lower()
+    for grp in org.get("groups", []):
+        for ag in grp.get("agents", []):
+            if ag.get("alias", "").lower() == key:
+                return ag.get("short") or ag.get("role")
+    return None
+
+
+def full_role_for(alias: str, org: dict[str, Any] | None = None) -> str | None:
+    """Same as role_for but returns the full snake_case role, never the short alias."""
+    if not alias:
+        return None
+    org = org or load_org()
+    key = alias.lower()
+    for grp in org.get("groups", []):
+        for ag in grp.get("agents", []):
+            if ag.get("alias", "").lower() == key:
+                return ag.get("role")
+    return None

package/payload/mishkan/observability/watch/src/mishkan_watch/skills_data.py

@@ -0,0 +1,267 @@
+"""Shared loader for installed skills and their cross-references to ADRs.
+
+Used by:
+  - tabs/skills.py — full Skills browser tab
+
+Independent of the skill-discovery indexer being built by Bezalel — the TUI
+needs a self-contained read-only view that works whether or not the
+indexer has run. If Bezalel's index.json exists, we prefer it; otherwise
+we fall back to scanning the canonical paths directly.
+
+What we expose
+--------------
+- load_skills() : list of skill entries with metadata
+- load_adr_index() : map adr id -> list of skill names mentioned there
+
+A skill entry:
+    {
+      "name": str,
+      "origin": "mishkan" | "user" | "plugin" | "project" | "builtin",
+      "source_path": str,
+      "description": str,
+      "category": str,
+      "frontmatter": dict,
+      "adrs": list[str],   # ADR ids that mention this skill, e.g. ["D-008"]
+    }
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+
+# Search order matters for name-collision resolution. First-hit wins.
+_SKILL_SOURCES = [
+    ("mishkan", Path.home() / ".claude" / "mishkan" / "skills"),
+    ("user",    Path.home() / ".claude" / "skills"),
+]
+
+
+def _plugin_skill_dirs() -> list[tuple[str, Path]]:
+    """Enumerate `~/.claude/plugins/*/skills/` lazily — order is filesystem order."""
+    out: list[tuple[str, Path]] = []
+    plugins = Path.home() / ".claude" / "plugins"
+    if not plugins.is_dir():
+        return out
+    try:
+        for child in plugins.iterdir():
+            sd = child / "skills"
+            if sd.is_dir():
+                out.append(("plugin", sd))
+    except OSError:
+        pass
+    return out
+
+
+def _all_sources() -> list[tuple[str, Path]]:
+    return list(_SKILL_SOURCES) + _plugin_skill_dirs()
+
+
+_FM_BLOCK_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+_FM_KV_RE = re.compile(r"^([A-Za-z_-]+):\s*(.*)$")
+_USE_WHEN_RE = re.compile(r"(?:Use when|use when|Use this skill when)\s+([^.\n]+)\.?", re.IGNORECASE)
+
+
+def _parse_skill_md(path: Path) -> dict[str, Any]:
+    """Parse a SKILL.md file. Returns frontmatter + body-derived hints.
+
+    Frontmatter is YAML-ish but we keep parsing simple — single-line
+    key: value pairs (no nested structures, no multiline values). Skills
+    that need more get represented as the raw frontmatter dict; the TUI
+    just shows what's there.
+    """
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return {}
+    fm: dict[str, Any] = {}
+    body = text
+    m = _FM_BLOCK_RE.match(text)
+    if m:
+        block = m.group(1)
+        body = text[m.end():]
+        for raw in block.splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            kv = _FM_KV_RE.match(line)
+            if kv:
+                fm[kv.group(1)] = kv.group(2).strip().strip('"').strip("'")
+    triggers: list[str] = []
+    for um in _USE_WHEN_RE.finditer(body):
+        triggers.append(um.group(1).strip())
+    return {"frontmatter": fm, "triggers": triggers, "body_chars": len(body)}
+
+
+def _category_for(path: Path, fm: dict[str, Any]) -> str:
+    """Heuristic category — first segment of the path under skills/, falling
+    back to a keyword scan of the description."""
+    try:
+        parts = path.parent.name
+    except Exception:
+        parts = ""
+    cat = parts
+    desc = (fm.get("description") or "").lower()
+    for keyword, label in (
+        ("security", "security"), ("frontend", "frontend"),
+        ("backend", "backend"), ("python", "python"),
+        ("kubernetes", "infra"), ("k8s", "infra"),
+        ("docker", "infra"), ("test", "testing"),
+        ("docs", "docs"), ("design", "design"),
+    ):
+        if keyword in desc:
+            cat = label
+            break
+    return cat or "uncategorised"
+
+
+def _load_indexer_output() -> list[dict[str, Any]] | None:
+    """If Bezalel's indexer has run, prefer its output."""
+    p = Path.home() / ".claude" / "mishkan" / "skill-discovery" / "index.json"
+    try:
+        if p.is_file():
+            data = json.loads(p.read_text())
+            if isinstance(data, dict) and "entries" in data:
+                return data["entries"]
+            if isinstance(data, list):
+                return data
+    except Exception:
+        return None
+    return None
+
+
+def load_skills() -> list[dict[str, Any]]:
+    """Return the full set of installed skills.
+
+    If `~/.claude/mishkan/skill-discovery/index.json` exists, use it;
+    otherwise scan the canonical paths directly. Entries are deduplicated
+    by skill name (first hit by source precedence wins).
+    """
+    indexed = _load_indexer_output()
+    if indexed:
+        adr_map = load_adr_index()
+        for e in indexed:
+            name = e.get("name") or ""
+            e["adrs"] = adr_map.get(name, [])
+        return indexed
+    out: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for origin, root in _all_sources():
+        if not root.is_dir():
+            continue
+        try:
+            # Two layouts: skills/<name>.md, or skills/<name>/SKILL.md.
+            for entry in sorted(root.iterdir()):
+                skill_md: Path | None = None
+                name: str | None = None
+                if entry.is_file() and entry.suffix == ".md":
+                    skill_md = entry
+                    name = entry.stem
+                elif entry.is_dir():
+                    cand = entry / "SKILL.md"
+                    if cand.is_file():
+                        skill_md = cand
+                        name = entry.name
+                if not skill_md or not name or name in seen:
+                    continue
+                seen.add(name)
+                parsed = _parse_skill_md(skill_md)
+                fm = parsed.get("frontmatter") or {}
+                out.append({
+                    "name": fm.get("name") or name,
+                    "origin": origin,
+                    "source_path": str(skill_md),
+                    "description": fm.get("description") or "",
+                    "category": _category_for(skill_md, fm),
+                    "frontmatter": fm,
+                    "triggers": parsed.get("triggers") or [],
+                    "adrs": [],
+                })
+        except OSError:
+            continue
+    adr_map = load_adr_index()
+    for e in out:
+        e["adrs"] = adr_map.get(e["name"], [])
+    return out
+
+
+_ADR_HEADER_RE = re.compile(r"^## (D-\d{3})\b", re.MULTILINE)
+
+
+def load_adr_index() -> dict[str, list[str]]:
+    """Map skill name -> list of ADR ids that mention it.
+
+    Parses `docs/design/MISHKAN_decisions.md`. Each ADR section is delimited
+    by `## D-NNN`; within each section we scan for any installed-skill name
+    that appears verbatim. This is conservative — a skill named `pdf` could
+    match noise, but we accept that for now (the alternative is a strict
+    whitelist that drifts).
+    """
+    decisions_path = _find_decisions_md()
+    if not decisions_path:
+        return {}
+    try:
+        text = decisions_path.read_text()
+    except OSError:
+        return {}
+    sections: list[tuple[str, str]] = []
+    cur_id: str | None = None
+    cur_buf: list[str] = []
+    for line in text.splitlines():
+        m = _ADR_HEADER_RE.match(line)
+        if m:
+            if cur_id is not None:
+                sections.append((cur_id, "\n".join(cur_buf)))
+            cur_id = m.group(1)
+            cur_buf = []
+        elif cur_id is not None:
+            cur_buf.append(line)
+    if cur_id is not None:
+        sections.append((cur_id, "\n".join(cur_buf)))
+    # Cross-ref against known skills — we need the name list, but at this
+    # point load_skills hasn't returned yet (would be circular). Instead
+    # scan all skill dir entries by name and look those up.
+    skill_names: set[str] = set()
+    for _, root in _all_sources():
+        if not root.is_dir():
+            continue
+        try:
+            for entry in root.iterdir():
+                if entry.is_file() and entry.suffix == ".md":
+                    skill_names.add(entry.stem)
+                elif entry.is_dir() and (entry / "SKILL.md").is_file():
+                    skill_names.add(entry.name)
+        except OSError:
+            continue
+    rev: dict[str, list[str]] = {}
+    for adr_id, body in sections:
+        for name in skill_names:
+            if not name:
+                continue
+            # Whole-word match — guard against substring noise.
+            if re.search(rf"\b{re.escape(name)}\b", body):
+                rev.setdefault(name, []).append(adr_id)
+    return rev
+
+
+def _find_decisions_md() -> Path | None:
+    """Locate MISHKAN_decisions.md. Prefer ~/.claude install path, fall back
+    to a repo-mode walk-up."""
+    candidates: list[Path] = [
+        Path.home() / ".claude" / "mishkan" / "design" / "MISHKAN_decisions.md",
+    ]
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        c = parent / "docs" / "design" / "MISHKAN_decisions.md"
+        if c.is_file():
+            candidates.append(c)
+            break
+        if parent == parent.parent:
+            break
+    for c in candidates:
+        if c.is_file():
+            return c
+    return None

package/payload/mishkan/observability/watch/src/mishkan_watch/tabs/agents.py

@@ -189,6 +189,11 @@ class AgentsTab(Container):
         root = tree.root
         root.expand()
         sessions = (self._state.get("sessions") or {})
+        # Daemon-side confirmed-alive gate (state.py) is the source of
+        # truth for what counts as a real session. Any session reaching
+        # us here is confirmed by session_discover. A residual project=""
+        # entry would be a daemon bug — surface it visually as "?" so we
+        # notice rather than silently hiding it.
         for sid, sess in sessions.items():
             label = Text()
             label.append(sid[:8] + "… ", style="cyan")
@@ -204,6 +209,9 @@ class AgentsTab(Container):
                     al = Text()
                     al.append("● ", style="#00D4AA")
                     al.append(name, style="bold")
+                    role = _role_for(name)
+                    if role:
+                        al.append(f"  · {role}", style="dim")
                     sess_node.add_leaf(al, data={"kind": "agent", "sid": sid, "agent": name})
 
     def on_tree_node_selected(self, event: Tree.NodeSelected) -> None:
@@ -271,8 +279,32 @@ class AgentsTab(Container):
                 p = ev.get("payload") or {}
                 ts = (ev.get("ts") or "")[11:19]
                 agent = ev.get("agent") or "(main)"
+                role = _role_for(agent) if agent != "(main)" else None
                 msg = (p.get("message") or "")[:60]
-                text.append(f"● {agent}  {ts}\n", style="#FC8181 bold")
+                label = f"{agent} · {role}" if role else agent
+                text.append(f"● {label}  {ts}\n", style="#FC8181 bold")
                 text.append(f"  {msg}\n", style="white")
                 text.append("─────────\n", style="dim")
         panel.update(text)
+
+
+# Module-level cache for the alias→role lookup (org.json is static).
+_ROLE_CACHE: dict[str, str | None] | None = None
+
+
+def _role_for(alias: str) -> str | None:
+    global _ROLE_CACHE
+    if _ROLE_CACHE is None:
+        try:
+            from ..org_data import load_org
+            org = load_org()
+            cache: dict[str, str | None] = {}
+            for grp in org.get("groups", []):
+                for ag in grp.get("agents", []):
+                    a = (ag.get("alias") or "").lower()
+                    if a:
+                        cache[a] = ag.get("short") or ag.get("role")
+            _ROLE_CACHE = cache
+        except Exception:
+            _ROLE_CACHE = {}
+    return _ROLE_CACHE.get((alias or "").lower())