shellbrain 0.1.3__tar.gz → 0.1.4__tar.gz

{shellbrain-0.1.3 → shellbrain-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.3
+Version: 0.1.4
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.3 → shellbrain-0.1.4}/app/periphery/cli/main.py

@@ -807,12 +807,17 @@ def _warn_or_fail_on_unsafe_app_role() -> None:
 
     from app.boot.admin_db import should_fail_on_unsafe_app_role
     from app.boot.db import get_db_dsn
-    from app.periphery.admin.instance_guard import inspect_role_safety
+    from app.periphery.admin.instance_guard import SCRATCH, TEST, fetch_instance_metadata, inspect_role_safety
 
-    warnings = inspect_role_safety(get_db_dsn())
+    dsn = get_db_dsn()
+    warnings = inspect_role_safety(dsn)
     if not warnings:
         return
     message = "Unsafe Shellbrain app-role configuration:\n- " + "\n- ".join(warnings)
+    metadata = fetch_instance_metadata(dsn)
+    if metadata is not None and metadata.instance_mode in {TEST, SCRATCH}:
+        print(message, file=sys.stderr)
+        return
     if should_fail_on_unsafe_app_role():
         raise ValueError(message)
     print(message, file=sys.stderr)

shellbrain-0.1.4/app/periphery/episodes/launcher.py

@@ -0,0 +1,36 @@
+"""Best-effort startup for the repo-local episodic sync poller."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+import sys
+
+from app.periphery.episodes.poller_lock import inspect_poller_lock
+
+
+def ensure_episode_sync_started(*, repo_id: str, repo_root: Path) -> bool:
+    """Start one detached poller process for the repo when needed."""
+
+    resolved_repo_root = repo_root.resolve()
+    inspection = inspect_poller_lock(repo_root=resolved_repo_root)
+    if inspection.active:
+        return False
+
+    command = [
+        sys.executable,
+        "-m",
+        "app.periphery.episodes.poller",
+        "--repo-id",
+        repo_id,
+        "--repo-root",
+        str(resolved_repo_root),
+    ]
+    subprocess.Popen(
+        command,
+        cwd=resolved_repo_root,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    return True

{shellbrain-0.1.3 → shellbrain-0.1.4}/app/periphery/episodes/poller.py

@@ -14,6 +14,7 @@ from uuid import uuid4
 from app.boot.use_cases import get_uow_factory
 from app.core.use_cases.record_episode_sync_telemetry import record_episode_sync_telemetry
 from app.core.use_cases.sync_episode import sync_episode_from_host
+from app.periphery.episodes.poller_lock import acquire_poller_lock, write_poller_pid_artifact
 from app.periphery.episodes.source_discovery import (
     SUPPORTED_HOSTS,
     default_search_roots,
@@ -52,126 +53,135 @@ def run_episode_poller(*, repo_id: str, repo_root: Path) -> None:
     """Run until the repo appears idle for long enough."""
 
     repo_root = repo_root.resolve()
+    lock_handle = acquire_poller_lock(repo_id=repo_id, repo_root=repo_root)
+    if lock_handle is None:
+        return
+
     known_state: dict[str, _HostState] = {}
     last_change_at = time.monotonic()
     uow_factory = get_uow_factory()
+    try:
+        _write_pid_artifact(repo_root=repo_root)
+        while True:
+            saw_change = False
+            for host_app in SUPPORTED_HOSTS:
+                search_roots = default_search_roots(repo_root=repo_root, host_app=host_app)
+                candidate = discover_active_host_session(
+                    host_app=host_app,
+                    repo_root=repo_root,
+                    search_roots=search_roots,
+                )
 
-    while True:
-        saw_change = False
-        for host_app in SUPPORTED_HOSTS:
-            search_roots = default_search_roots(repo_root=repo_root, host_app=host_app)
-            candidate = discover_active_host_session(
-                host_app=host_app,
-                repo_root=repo_root,
-                search_roots=search_roots,
-            )
-
-            if candidate is None:
-                if host_app in known_state:
-                    _record_missing_source(
-                        repo_root=repo_root,
+                if candidate is None:
+                    if host_app in known_state:
+                        _record_missing_source(
+                            repo_root=repo_root,
+                            host_app=host_app,
+                            host_session_key=known_state[host_app].session_key,
+                            search_roots=search_roots,
+                            last_known_path=known_state[host_app].transcript_path,
+                        )
+                    continue
+
+                transcript_path = Path(candidate["transcript_path"])
+                state = known_state.get(host_app)
+                session_changed = state is not None and state.session_key != candidate["host_session_key"]
+                if session_changed:
+                    _close_episode(
+                        repo_id=repo_id,
                         host_app=host_app,
-                        host_session_key=known_state[host_app].session_key,
-                        search_roots=search_roots,
-                        last_known_path=known_state[host_app].transcript_path,
+                        host_session_key=state.session_key,
+                        uow_factory=uow_factory,
                     )
-                continue
-
-            transcript_path = Path(candidate["transcript_path"])
-            state = known_state.get(host_app)
-            session_changed = state is not None and state.session_key != candidate["host_session_key"]
-            if session_changed:
-                _close_episode(
-                    repo_id=repo_id,
-                    host_app=host_app,
-                    host_session_key=state.session_key,
-                    uow_factory=uow_factory,
-                )
 
-            mtime = transcript_path.stat().st_mtime if transcript_path.exists() else 0.0
-            should_sync = state is None or session_changed or state.last_mtime != mtime
-            known_state[host_app] = _HostState(
-                session_key=str(candidate["host_session_key"]),
-                transcript_path=transcript_path,
-                last_mtime=mtime,
-            )
-            if not should_sync:
-                continue
-
-            sync_started_at = perf_counter()
-            try:
-                with uow_factory() as uow:
-                    sync_result = sync_episode_from_host(
+                mtime = transcript_path.stat().st_mtime if transcript_path.exists() else 0.0
+                should_sync = state is None or session_changed or state.last_mtime != mtime
+                known_state[host_app] = _HostState(
+                    session_key=str(candidate["host_session_key"]),
+                    transcript_path=transcript_path,
+                    last_mtime=mtime,
+                )
+                if not should_sync:
+                    continue
+
+                sync_started_at = perf_counter()
+                try:
+                    with uow_factory() as uow:
+                        sync_result = sync_episode_from_host(
+                            repo_id=repo_id,
+                            host_app=host_app,
+                            host_session_key=str(candidate["host_session_key"]),
+                            uow=uow,
+                            search_roots=search_roots,
+                            last_known_path=transcript_path,
+                        )
+                    _record_status(
+                        repo_root=repo_root,
+                        host_app=host_app,
+                        host_session_key=str(candidate["host_session_key"]),
+                        last_successful_sync_at=_utc_now().isoformat(),
+                        last_error=None,
+                    )
+                    _record_sync_telemetry_best_effort(
+                        uow_factory=uow_factory,
                         repo_id=repo_id,
                         host_app=host_app,
                         host_session_key=str(candidate["host_session_key"]),
-                        uow=uow,
-                        search_roots=search_roots,
-                        last_known_path=transcript_path,
+                        thread_id=str(sync_result["thread_id"]),
+                        episode_id=str(sync_result["episode_id"]),
+                        transcript_path=str(sync_result["transcript_path"]),
+                        outcome="ok",
+                        error_stage=None,
+                        error_message=None,
+                        duration_ms=int((perf_counter() - sync_started_at) * 1000),
+                        imported_event_count=int(sync_result["imported_event_count"]),
+                        total_event_count=int(sync_result["total_event_count"]),
+                        user_event_count=int(sync_result["user_event_count"]),
+                        assistant_event_count=int(sync_result["assistant_event_count"]),
+                        tool_event_count=int(sync_result["tool_event_count"]),
+                        system_event_count=int(sync_result["system_event_count"]),
+                        tool_type_counts=dict(sync_result["tool_type_counts"]),
                     )
-                _record_status(
-                    repo_root=repo_root,
-                    host_app=host_app,
-                    host_session_key=str(candidate["host_session_key"]),
-                    last_successful_sync_at=_utc_now().isoformat(),
-                    last_error=None,
-                )
-                _record_sync_telemetry_best_effort(
-                    uow_factory=uow_factory,
-                    repo_id=repo_id,
-                    host_app=host_app,
-                    host_session_key=str(candidate["host_session_key"]),
-                    thread_id=str(sync_result["thread_id"]),
-                    episode_id=str(sync_result["episode_id"]),
-                    transcript_path=str(sync_result["transcript_path"]),
-                    outcome="ok",
-                    error_stage=None,
-                    error_message=None,
-                    duration_ms=int((perf_counter() - sync_started_at) * 1000),
-                    imported_event_count=int(sync_result["imported_event_count"]),
-                    total_event_count=int(sync_result["total_event_count"]),
-                    user_event_count=int(sync_result["user_event_count"]),
-                    assistant_event_count=int(sync_result["assistant_event_count"]),
-                    tool_event_count=int(sync_result["tool_event_count"]),
-                    system_event_count=int(sync_result["system_event_count"]),
-                    tool_type_counts=dict(sync_result["tool_type_counts"]),
-                )
-                saw_change = True
-            except Exception as exc:
-                _record_status(
-                    repo_root=repo_root,
-                    host_app=host_app,
-                    host_session_key=str(candidate["host_session_key"]),
-                    last_successful_sync_at=None,
-                    last_error=str(exc),
-                )
-                _record_sync_telemetry_best_effort(
-                    uow_factory=uow_factory,
-                    repo_id=repo_id,
-                    host_app=host_app,
-                    host_session_key=str(candidate["host_session_key"]),
-                    thread_id=f"{host_app}:{candidate['host_session_key']}",
-                    episode_id=None,
-                    transcript_path=str(transcript_path),
-                    outcome="error",
-                    error_stage="sync",
-                    error_message=str(exc),
-                    duration_ms=int((perf_counter() - sync_started_at) * 1000),
-                    imported_event_count=0,
-                    total_event_count=0,
-                    user_event_count=0,
-                    assistant_event_count=0,
-                    tool_event_count=0,
-                    system_event_count=0,
-                    tool_type_counts={},
-                )
+                    saw_change = True
+                except Exception as exc:
+                    _record_status(
+                        repo_root=repo_root,
+                        host_app=host_app,
+                        host_session_key=str(candidate["host_session_key"]),
+                        last_successful_sync_at=None,
+                        last_error=str(exc),
+                    )
+                    _record_sync_telemetry_best_effort(
+                        uow_factory=uow_factory,
+                        repo_id=repo_id,
+                        host_app=host_app,
+                        host_session_key=str(candidate["host_session_key"]),
+                        thread_id=f"{host_app}:{candidate['host_session_key']}",
+                        episode_id=None,
+                        transcript_path=str(transcript_path),
+                        outcome="error",
+                        error_stage="sync",
+                        error_message=str(exc),
+                        duration_ms=int((perf_counter() - sync_started_at) * 1000),
+                        imported_event_count=0,
+                        total_event_count=0,
+                        user_event_count=0,
+                        assistant_event_count=0,
+                        tool_event_count=0,
+                        system_event_count=0,
+                        tool_type_counts={},
+                    )
+
+            if saw_change:
+                last_change_at = time.monotonic()
+            elif time.monotonic() - last_change_at >= IDLE_EXIT_SECONDS:
+                break
+
+            time.sleep(POLL_INTERVAL_SECONDS)
+    finally:
+        lock_handle.release()
 
-        if saw_change:
-            last_change_at = time.monotonic()
-        elif time.monotonic() - last_change_at >= IDLE_EXIT_SECONDS:
-            break
 
-        time.sleep(POLL_INTERVAL_SECONDS)
 def _close_episode(*, repo_id: str, host_app: str, host_session_key: str, uow_factory) -> None:
     """Close one active episode when a newer session replaces it."""
 
@@ -237,6 +247,12 @@ def _record_status(
     status_path.write_text(json.dumps(status, indent=2, sort_keys=True), encoding="utf-8")
 
 
+def _write_pid_artifact(*, repo_root: Path) -> None:
+    """Persist the compatibility pid artifact for the current poller process."""
+
+    write_poller_pid_artifact(repo_root=repo_root)
+
+
 def _utc_now() -> datetime:
     """Return a timezone-aware current UTC time."""
 

shellbrain-0.1.4/app/periphery/episodes/poller_lock.py

@@ -0,0 +1,225 @@
+"""Repo-local singleton lock helpers for the episode poller."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import shutil
+import socket
+
+
+_LOCK_DIR_NAME = "episode_sync.lock"
+_OWNER_FILENAME = "owner.json"
+_PID_FILENAME = "episode_sync.pid"
+
+
+@dataclass(frozen=True)
+class PollerLockInspection:
+    """Current status of the repo-local poller singleton lock."""
+
+    lock_root: Path
+    owner_path: Path
+    status: str
+    owner: dict[str, object] | None
+
+    @property
+    def active(self) -> bool:
+        """Return whether the lock currently belongs to a live owner."""
+
+        return self.status in {"active", "foreign_active"}
+
+
+@dataclass
+class PollerLockHandle:
+    """Lease for one acquired poller lock."""
+
+    repo_root: Path
+    lock_root: Path
+    owner_path: Path
+    owner: dict[str, object]
+    released: bool = False
+
+    def release(self) -> None:
+        """Release the repo-local lock when still owned by this process."""
+
+        if self.released:
+            return
+        release_poller_lock(self)
+        self.released = True
+
+
+def inspect_poller_lock(*, repo_root: Path) -> PollerLockInspection:
+    """Inspect the current poller singleton lock for one repo root."""
+
+    resolved_repo_root = repo_root.resolve()
+    lock_root = _lock_root(resolved_repo_root)
+    owner_path = lock_root / _OWNER_FILENAME
+    if not lock_root.exists():
+        return PollerLockInspection(lock_root=lock_root, owner_path=owner_path, status="unlocked", owner=None)
+    if not lock_root.is_dir():
+        return PollerLockInspection(lock_root=lock_root, owner_path=owner_path, status="stale", owner=None)
+
+    owner = _read_owner_payload(owner_path)
+    if owner is None or not _owner_payload_is_well_formed(owner=owner, repo_root=resolved_repo_root):
+        return PollerLockInspection(lock_root=lock_root, owner_path=owner_path, status="stale", owner=owner)
+
+    hostname = str(owner["hostname"])
+    if hostname != _current_hostname():
+        return PollerLockInspection(lock_root=lock_root, owner_path=owner_path, status="foreign_active", owner=owner)
+
+    pid = int(owner["pid"])
+    if _is_process_running(pid):
+        return PollerLockInspection(lock_root=lock_root, owner_path=owner_path, status="active", owner=owner)
+    return PollerLockInspection(lock_root=lock_root, owner_path=owner_path, status="stale", owner=owner)
+
+
+def acquire_poller_lock(*, repo_id: str, repo_root: Path) -> PollerLockHandle | None:
+    """Acquire the repo-local singleton lock, returning None when another owner is active."""
+
+    resolved_repo_root = repo_root.resolve()
+    runtime_dir = resolved_repo_root / ".shellbrain"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    lock_root = _lock_root(resolved_repo_root)
+    owner_path = lock_root / _OWNER_FILENAME
+    owner = _build_owner_payload(repo_id=repo_id, repo_root=resolved_repo_root)
+
+    for _attempt in range(2):
+        try:
+            lock_root.mkdir()
+        except FileExistsError:
+            inspection = inspect_poller_lock(repo_root=resolved_repo_root)
+            if inspection.active:
+                return None
+            if inspection.status == "stale":
+                _remove_stale_lock(lock_root=lock_root, expected_owner=inspection.owner)
+                continue
+            return None
+
+        try:
+            owner_path.write_text(json.dumps(owner, indent=2, sort_keys=True), encoding="utf-8")
+        except Exception:
+            _remove_path(lock_root)
+            raise
+        return PollerLockHandle(
+            repo_root=resolved_repo_root,
+            lock_root=lock_root,
+            owner_path=owner_path,
+            owner=owner,
+        )
+
+    return None
+
+
+def release_poller_lock(handle: PollerLockHandle) -> None:
+    """Release the singleton lock when the on-disk owner still matches this handle."""
+
+    inspection = inspect_poller_lock(repo_root=handle.repo_root)
+    if inspection.status == "unlocked":
+        return
+    if inspection.owner != handle.owner:
+        return
+
+    try:
+        handle.owner_path.unlink(missing_ok=True)
+    except OSError:
+        return
+    try:
+        handle.lock_root.rmdir()
+    except OSError:
+        return
+
+
+def write_poller_pid_artifact(*, repo_root: Path) -> Path:
+    """Persist the compatibility pid artifact for the current poller process."""
+
+    resolved_repo_root = repo_root.resolve()
+    runtime_dir = resolved_repo_root / ".shellbrain"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    pid_path = runtime_dir / _PID_FILENAME
+    pid_path.write_text(json.dumps({"pid": os.getpid()}, indent=2, sort_keys=True), encoding="utf-8")
+    return pid_path
+
+
+def _lock_root(repo_root: Path) -> Path:
+    """Return the canonical lock directory path for one repo root."""
+
+    return repo_root / ".shellbrain" / _LOCK_DIR_NAME
+
+
+def _build_owner_payload(*, repo_id: str, repo_root: Path) -> dict[str, object]:
+    """Build the owner metadata stored inside the singleton lock."""
+
+    return {
+        "hostname": _current_hostname(),
+        "pid": os.getpid(),
+        "repo_id": repo_id,
+        "repo_root": str(repo_root),
+        "started_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def _read_owner_payload(owner_path: Path) -> dict[str, object] | None:
+    """Read the owner metadata for one existing lock when present."""
+
+    try:
+        payload = json.loads(owner_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, NotADirectoryError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _owner_payload_is_well_formed(*, owner: dict[str, object], repo_root: Path) -> bool:
+    """Return whether one owner payload is usable for lock inspection."""
+
+    return (
+        isinstance(owner.get("pid"), int)
+        and isinstance(owner.get("hostname"), str)
+        and bool(str(owner.get("hostname")))
+        and isinstance(owner.get("repo_id"), str)
+        and owner.get("repo_root") == str(repo_root)
+        and isinstance(owner.get("started_at"), str)
+    )
+
+
+def _remove_stale_lock(*, lock_root: Path, expected_owner: dict[str, object] | None) -> None:
+    """Remove one stale lock only when the current stale owner still matches the expected state."""
+
+    if not lock_root.exists():
+        return
+    inspection = inspect_poller_lock(repo_root=lock_root.parent.parent)
+    if inspection.status != "stale":
+        return
+    if expected_owner is not None and inspection.owner != expected_owner:
+        return
+    _remove_path(lock_root)
+
+
+def _remove_path(path: Path) -> None:
+    """Remove one filesystem path whether it is a file or directory."""
+
+    if path.is_dir():
+        shutil.rmtree(path, ignore_errors=True)
+        return
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        return
+
+
+def _current_hostname() -> str:
+    """Return the normalized current hostname for lock ownership checks."""
+
+    return socket.gethostname().strip().lower()
+
+
+def _is_process_running(pid: int) -> bool:
+    """Return whether one pid is currently alive on this host."""
+
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True

{shellbrain-0.1.3 → shellbrain-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shellbrain"
-version = "0.1.3"
+version = "0.1.4"
 description = "Repo-scoped Shellbrain CLI with explicit evidence-backed writes."
 readme = "README.md"
 requires-python = ">=3.11"

{shellbrain-0.1.3 → shellbrain-0.1.4}/shellbrain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.3
+Version: 0.1.4
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.3 → shellbrain-0.1.4}/shellbrain.egg-info/SOURCES.txt

@@ -152,6 +152,7 @@ app/periphery/episodes/codex.py
 app/periphery/episodes/launcher.py
 app/periphery/episodes/normalization.py
 app/periphery/episodes/poller.py
+app/periphery/episodes/poller_lock.py
 app/periphery/episodes/source_discovery.py
 app/periphery/episodes/tool_filter.py
 app/periphery/identity/__init__.py

shellbrain-0.1.3/app/periphery/episodes/launcher.py

@@ -1,66 +0,0 @@
-"""Best-effort startup for the repo-local episodic sync poller."""
-
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-import subprocess
-import sys
-
-
-_PID_FILE = "episode_sync.pid"
-
-
-def ensure_episode_sync_started(*, repo_id: str, repo_root: Path) -> bool:
-    """Start one detached poller process for the repo when needed."""
-
-    runtime_dir = repo_root / ".shellbrain"
-    runtime_dir.mkdir(parents=True, exist_ok=True)
-    pid_path = runtime_dir / _PID_FILE
-
-    existing_pid = _read_pid(pid_path)
-    if existing_pid is not None and _is_running(existing_pid):
-        return False
-
-    command = [
-        sys.executable,
-        "-m",
-        "app.periphery.episodes.poller",
-        "--repo-id",
-        repo_id,
-        "--repo-root",
-        str(repo_root),
-    ]
-    process = subprocess.Popen(
-        command,
-        cwd=repo_root,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-        start_new_session=True,
-    )
-    pid_path.write_text(json.dumps({"pid": process.pid}), encoding="utf-8")
-    return True
-
-
-def _read_pid(pid_path: Path) -> int | None:
-    """Read one stored pid from disk when available."""
-
-    if not pid_path.exists():
-        return None
-    try:
-        payload = json.loads(pid_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError:
-        return None
-    pid = payload.get("pid")
-    return int(pid) if isinstance(pid, int) else None
-
-
-def _is_running(pid: int) -> bool:
-    """Return whether one process id is still alive."""
-
-    try:
-        os.kill(pid, 0)
-    except OSError:
-        return False
-    return True