alter-runtime 0.3.2__tar.gz → 0.4.8__tar.gz

{alter_runtime-0.3.2 → alter_runtime-0.4.8}/.gitignore

@@ -22,7 +22,18 @@ htmlcov/
 .vscode/
 .idea/
 
-# Wave 2+ generated artefacts (local daemon state — never in the repo)
+# Generated daemon artefacts (local daemon state, never in the repo)
 *.sock
 keypair.json
 runtime.yaml
+
+# Binary build outputs
+out/
+.pyinstaller-workdir/
+.pyinstaller-dist/
+.venv-pyinstaller/
+*.spec.toc
+*.toc
+*.pkg
+*.exe
+*.app/

{alter_runtime-0.3.2 → alter_runtime-0.4.8}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: alter-runtime
-Version: 0.3.2
-Summary: ~Alter Identity Runtime - local sovereign daemon for the continuous identity field. Subscribes to per-~handle Cloudflare Durable Objects, exposes Unix socket + D-Bus + CLI surfaces, falls back gracefully to direct MCP polling.
+Version: 0.4.8
+Summary: ~Alter Identity Runtime - local daemon for the continuous identity field. Subscribes to per-~handle Cloudflare Durable Objects, exposes Unix socket + D-Bus + CLI surfaces, falls back gracefully to direct MCP polling.
 Project-URL: Homepage, https://truealter.com
 Project-URL: Documentation, https://truealter.com/docs/alter-runtime
 Project-URL: Repository, https://github.com/true-alter/alter-runtime
 Project-URL: Bug Tracker, https://github.com/true-alter/alter-runtime/issues
-Author: Blake Morrison
+Author: ~Alter
 Author-email: ALTER Meridian Pty Ltd <hello@truealter.com>
 License: Apache-2.0
 License-File: LICENSE
@@ -68,13 +68,10 @@ Description-Content-Type: text/markdown
 
 # alter-runtime - ~Alter Identity Runtime
 
-> **L3 of the six-layer identity distribution surface.** The local sovereign daemon that
-> lives alongside you, subscribes to your per-`~handle` Cloudflare Durable Object, and
-> renders your identity field across every surface your device touches - terminal, IDE,
-> status bars, desktop tray, browser extension. Falls back gracefully to direct MCP
-> polling when the edge is unreachable.
-
-The alter-runtime daemon architecture was established in April 2026.
+> The local daemon that lives alongside you, subscribes to your per-`~handle`
+> Cloudflare Durable Object, and renders your identity field across every surface
+> your device touches - terminal, IDE, status bars, desktop tray, browser extension.
+> Falls back gracefully to direct MCP polling when the edge is unreachable.
 
 ## Alpha release - filesystem key storage
 
@@ -100,7 +97,7 @@ documented fallback.
 compromise would imply identity compromise - pair the runtime with
 hardware-attested passkey registration via the browser claim flow (graduated
 attestation). The filesystem-stored device key then scopes only to ambient
-signal ingestion, not to Sovereign-tier authorisations, which require a fresh
+signal ingestion, not to high-assurance authorisations, which require a fresh
 hardware passkey ceremony per session.
 
 **Reporting issues.** Security-relevant reports: please follow
@@ -110,16 +107,9 @@ filing a public issue. Non-security bugs and feature requests: email
 
 ## Status
 
-| Wave | Stream | Status |
-|------|--------|--------|
-| 1 | 1c - Daemon skeleton + `AlterClient` SDK | Shipped |
-| 2 | 2b - Subscribers, Unix socket, D-Bus, git watcher | Shipped |
-| 2 | 2c - systemd + launchd service units | Shipped |
-| 2 | 2d - First pixel: CC hook + scripts upgrade | Shipped |
-| 2 | 2e - eBPF subscriber (reference impl in `alter-ebpf`) | Shipped |
-| 3 | 3a - Cross-platform tray surfaces | Planned |
-| 3 | 3b - Windows Service + `pam_alter` stub | Planned |
-| 3 | 3c - PyPI release CI + signed binaries | Planned |
+Shipped: the daemon and `AlterClient` SDK; subscribers, the Unix socket,
+D-Bus, and the git watcher; systemd and launchd service units; the local
+editor and shell hook surfaces; and the eBPF subscriber.
 
 ## Install
 
@@ -167,7 +157,7 @@ alter-runtime stop
    at `https://mcp.truealter.com/events/~yourhandle/stream`. Events arrive with ~50ms
    latency worldwide.
 
-2. **Falls back gracefully** to direct polling of the ALTER MCP endpoint at
+2. **Falls back gracefully** to direct polling of the `~alter` MCP endpoint at
    `https://api.truealter.com/api/v1/mcp` when the DO is unreachable for more than 3
    seconds. Your surfaces never know which path served them.
 
@@ -176,18 +166,18 @@ alter-runtime stop
      `~/Library/Application Support/alter/runtime.sock` (macOS) - line-delimited JSON
    - **D-Bus** interface `org.alter.Identity1` on the session bus (Linux) - used by
      GNOME/KDE/Waybar modules
-   - **HTTP/SSE** loopback at `http://127.0.0.1:<port>/events` - used by the CC hook
-     and shell scripts
+   - **HTTP/SSE** loopback at `http://127.0.0.1:<port>/events` - used by local
+     editor hooks and shell scripts
 
-4. **Collects ambient signals** via adapters (Wave 2):
+4. **Collects ambient signals** via adapters:
    - Git commits, branch switches, pushes (via `watchdog` on `.git/refs/heads/`)
-   - CC hook events (forwarded from `.claude/hooks/*.sh`)
+   - Editor session hook events (forwarded from local shell hooks)
    - Shell command invocations (opt-in)
-   - eBPF kernel attestations (shipped; reference impl in `alter-ebpf`)
+   - eBPF kernel attestations (shipped)
 
 5. **Maintains a local cache** of your last-known-good field state so the first-paint
-   tilde warmth renders in <1 second, even offline. Per IFA's Five OS-Native Properties,
-   this is the **monotonic continuity** guarantee.
+   tilde warmth renders in <1 second, even offline. The cached state always renders,
+   so your surfaces stay continuous across restarts and network drops.
 
 ## Layout
 
@@ -198,21 +188,21 @@ alter-runtime/
 ├── LICENSE
 ├── alter_runtime/
 │   ├── __init__.py
-│   ├── config.py                 # XDG loader, reads alter-cli session.json
+│   ├── config.py                 # XDG loader, reads the CLI session.json
 │   ├── daemon.py                 # asyncio supervisor
 │   ├── cli.py                    # argparse entrypoint: init|start|stop|status|query|ingest|daemon
 │   ├── sdk/
 │   │   ├── __init__.py
 │   │   └── client.py             # AlterClient (async identity MCP client)
-│   ├── subscribers/              # (Wave 2)
-│   │   ├── do_sse.py             # primary - subscribes to handle-alter DO SSE
+│   ├── subscribers/
+│   │   ├── do_sse.py             # primary - subscribes to the per-handle DO SSE stream
 │   │   └── mcp_fallback.py       # fallback - polls api.truealter.com/api/v1/mcp
-│   ├── sockets/                  # (Wave 2)
+│   ├── sockets/
 │   │   ├── unix.py               # /run/user/$UID/alter.sock
 │   │   └── dbus.py               # org.alter.Identity1
-│   ├── adapters/                 # (Wave 2)
+│   ├── adapters/
 │   │   └── git_watcher.py        # watchdog on .git/refs/heads/
-│   └── services/                 # (Wave 2)
+│   └── services/
 │       ├── systemd/alter-runtime.service
 │       ├── launchd/com.alter.runtime.plist
 │       └── windows/AlterRuntimeService.py
@@ -249,41 +239,19 @@ asyncio.run(main())
 
 ## Packaging
 
-- **PyPI** - `pip install alter-runtime` (publish is tag-gated; see
-  `.github/workflows/ci.yml`).
-- **AUR** - draft PKGBUILD at [`aur/PKGBUILD`](aur/PKGBUILD). Submission is
-  blocked on the PyPI publish resolving the sdist URL. Regenerate `.SRCINFO`
-  with `makepkg --printsrcinfo > .SRCINFO` before AUR upload.
-- **`truealter` PyPI shim** - thin console-script package at
-  [`pypi-truealter/`](pypi-truealter/) that execs the npm-installed
-  `alter` binary. Distinct from `alter-runtime`: `pip install truealter`
-  gets pip-centric users a fourth CLI install channel alongside npm,
-  Homebrew (planned), and the AUR (planned). Tag format
-  `truealter-v<version>`; see
-  [`.github/workflows/truealter-publish.yml`](.github/workflows/truealter-publish.yml).
-
-## Contributing
-
-After cloning, wire the identity-trailer hook so commits land with `Acted-By:`, `Drafted-With:`, and `Co-Authored-By:` trailers automatically:
-
-```
-bash scripts/setup-githooks.sh
-```
-
-The helper sets the local `core.hooksPath` to `.githooks/` and marks every hook executable. It is idempotent - safe to re-run after pulls. Equivalent one-liner without the helper:
-
-```
-git config core.hooksPath .githooks
-```
+`alter-runtime` is distributed through several install channels:
 
-The hook reads your ALTER session at `~/.config/alter/session.json` (run `alter login` from the [`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli) once) plus `$CLAUDE_MODEL` for the Instrument tier attribution. It is silent when the session is missing or `jq` is unavailable, so a contributor without an ALTER session still gets a normal commit; the CI verifier catches missing trailers at PR time (warn-only during the Rung 1/2 migration window).
+- **PyPI** - `pip install alter-runtime`
+- **Arch Linux (AUR)** - `alter-runtime`
+- **Homebrew** - `brew install alter-runtime`
 
-Python projects don't have npm's `prepare`-on-install lifecycle, so this step is manual - done once after clone and persisted in your local `.git/config`.
+Pin an exact version in downstream tooling during the alpha and read the
+CHANGELOG before upgrading.
 
 ## Related projects
 
 - [`@truealter/sdk`](https://www.npmjs.com/package/@truealter/sdk) - TypeScript
   SDK client for the public MCP server.
-- ALTER MCP endpoint - `https://mcp.truealter.com` (SSE per-`~handle` stream)
+- `~alter` MCP endpoint - `https://mcp.truealter.com` (SSE per-`~handle` stream)
   and `https://api.truealter.com/api/v1/mcp` (HTTP fallback). Both are documented
   at [truealter.com](https://truealter.com).

{alter_runtime-0.3.2 → alter_runtime-0.4.8}/README.md

@@ -1,12 +1,9 @@
 # alter-runtime - ~Alter Identity Runtime
 
-> **L3 of the six-layer identity distribution surface.** The local sovereign daemon that
-> lives alongside you, subscribes to your per-`~handle` Cloudflare Durable Object, and
-> renders your identity field across every surface your device touches - terminal, IDE,
-> status bars, desktop tray, browser extension. Falls back gracefully to direct MCP
-> polling when the edge is unreachable.
-
-The alter-runtime daemon architecture was established in April 2026.
+> The local daemon that lives alongside you, subscribes to your per-`~handle`
+> Cloudflare Durable Object, and renders your identity field across every surface
+> your device touches - terminal, IDE, status bars, desktop tray, browser extension.
+> Falls back gracefully to direct MCP polling when the edge is unreachable.
 
 ## Alpha release - filesystem key storage
 
@@ -32,7 +29,7 @@ documented fallback.
 compromise would imply identity compromise - pair the runtime with
 hardware-attested passkey registration via the browser claim flow (graduated
 attestation). The filesystem-stored device key then scopes only to ambient
-signal ingestion, not to Sovereign-tier authorisations, which require a fresh
+signal ingestion, not to high-assurance authorisations, which require a fresh
 hardware passkey ceremony per session.
 
 **Reporting issues.** Security-relevant reports: please follow
@@ -42,16 +39,9 @@ filing a public issue. Non-security bugs and feature requests: email
 
 ## Status
 
-| Wave | Stream | Status |
-|------|--------|--------|
-| 1 | 1c - Daemon skeleton + `AlterClient` SDK | Shipped |
-| 2 | 2b - Subscribers, Unix socket, D-Bus, git watcher | Shipped |
-| 2 | 2c - systemd + launchd service units | Shipped |
-| 2 | 2d - First pixel: CC hook + scripts upgrade | Shipped |
-| 2 | 2e - eBPF subscriber (reference impl in `alter-ebpf`) | Shipped |
-| 3 | 3a - Cross-platform tray surfaces | Planned |
-| 3 | 3b - Windows Service + `pam_alter` stub | Planned |
-| 3 | 3c - PyPI release CI + signed binaries | Planned |
+Shipped: the daemon and `AlterClient` SDK; subscribers, the Unix socket,
+D-Bus, and the git watcher; systemd and launchd service units; the local
+editor and shell hook surfaces; and the eBPF subscriber.
 
 ## Install
 
@@ -99,7 +89,7 @@ alter-runtime stop
    at `https://mcp.truealter.com/events/~yourhandle/stream`. Events arrive with ~50ms
    latency worldwide.
 
-2. **Falls back gracefully** to direct polling of the ALTER MCP endpoint at
+2. **Falls back gracefully** to direct polling of the `~alter` MCP endpoint at
    `https://api.truealter.com/api/v1/mcp` when the DO is unreachable for more than 3
    seconds. Your surfaces never know which path served them.
 
@@ -108,18 +98,18 @@ alter-runtime stop
      `~/Library/Application Support/alter/runtime.sock` (macOS) - line-delimited JSON
    - **D-Bus** interface `org.alter.Identity1` on the session bus (Linux) - used by
      GNOME/KDE/Waybar modules
-   - **HTTP/SSE** loopback at `http://127.0.0.1:<port>/events` - used by the CC hook
-     and shell scripts
+   - **HTTP/SSE** loopback at `http://127.0.0.1:<port>/events` - used by local
+     editor hooks and shell scripts
 
-4. **Collects ambient signals** via adapters (Wave 2):
+4. **Collects ambient signals** via adapters:
    - Git commits, branch switches, pushes (via `watchdog` on `.git/refs/heads/`)
-   - CC hook events (forwarded from `.claude/hooks/*.sh`)
+   - Editor session hook events (forwarded from local shell hooks)
    - Shell command invocations (opt-in)
-   - eBPF kernel attestations (shipped; reference impl in `alter-ebpf`)
+   - eBPF kernel attestations (shipped)
 
 5. **Maintains a local cache** of your last-known-good field state so the first-paint
-   tilde warmth renders in <1 second, even offline. Per IFA's Five OS-Native Properties,
-   this is the **monotonic continuity** guarantee.
+   tilde warmth renders in <1 second, even offline. The cached state always renders,
+   so your surfaces stay continuous across restarts and network drops.
 
 ## Layout
 
@@ -130,21 +120,21 @@ alter-runtime/
 ├── LICENSE
 ├── alter_runtime/
 │   ├── __init__.py
-│   ├── config.py                 # XDG loader, reads alter-cli session.json
+│   ├── config.py                 # XDG loader, reads the CLI session.json
 │   ├── daemon.py                 # asyncio supervisor
 │   ├── cli.py                    # argparse entrypoint: init|start|stop|status|query|ingest|daemon
 │   ├── sdk/
 │   │   ├── __init__.py
 │   │   └── client.py             # AlterClient (async identity MCP client)
-│   ├── subscribers/              # (Wave 2)
-│   │   ├── do_sse.py             # primary - subscribes to handle-alter DO SSE
+│   ├── subscribers/
+│   │   ├── do_sse.py             # primary - subscribes to the per-handle DO SSE stream
 │   │   └── mcp_fallback.py       # fallback - polls api.truealter.com/api/v1/mcp
-│   ├── sockets/                  # (Wave 2)
+│   ├── sockets/
 │   │   ├── unix.py               # /run/user/$UID/alter.sock
 │   │   └── dbus.py               # org.alter.Identity1
-│   ├── adapters/                 # (Wave 2)
+│   ├── adapters/
 │   │   └── git_watcher.py        # watchdog on .git/refs/heads/
-│   └── services/                 # (Wave 2)
+│   └── services/
 │       ├── systemd/alter-runtime.service
 │       ├── launchd/com.alter.runtime.plist
 │       └── windows/AlterRuntimeService.py
@@ -181,41 +171,19 @@ asyncio.run(main())
 
 ## Packaging
 
-- **PyPI** - `pip install alter-runtime` (publish is tag-gated; see
-  `.github/workflows/ci.yml`).
-- **AUR** - draft PKGBUILD at [`aur/PKGBUILD`](aur/PKGBUILD). Submission is
-  blocked on the PyPI publish resolving the sdist URL. Regenerate `.SRCINFO`
-  with `makepkg --printsrcinfo > .SRCINFO` before AUR upload.
-- **`truealter` PyPI shim** - thin console-script package at
-  [`pypi-truealter/`](pypi-truealter/) that execs the npm-installed
-  `alter` binary. Distinct from `alter-runtime`: `pip install truealter`
-  gets pip-centric users a fourth CLI install channel alongside npm,
-  Homebrew (planned), and the AUR (planned). Tag format
-  `truealter-v<version>`; see
-  [`.github/workflows/truealter-publish.yml`](.github/workflows/truealter-publish.yml).
-
-## Contributing
-
-After cloning, wire the identity-trailer hook so commits land with `Acted-By:`, `Drafted-With:`, and `Co-Authored-By:` trailers automatically:
-
-```
-bash scripts/setup-githooks.sh
-```
-
-The helper sets the local `core.hooksPath` to `.githooks/` and marks every hook executable. It is idempotent - safe to re-run after pulls. Equivalent one-liner without the helper:
-
-```
-git config core.hooksPath .githooks
-```
+`alter-runtime` is distributed through several install channels:
 
-The hook reads your ALTER session at `~/.config/alter/session.json` (run `alter login` from the [`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli) once) plus `$CLAUDE_MODEL` for the Instrument tier attribution. It is silent when the session is missing or `jq` is unavailable, so a contributor without an ALTER session still gets a normal commit; the CI verifier catches missing trailers at PR time (warn-only during the Rung 1/2 migration window).
+- **PyPI** - `pip install alter-runtime`
+- **Arch Linux (AUR)** - `alter-runtime`
+- **Homebrew** - `brew install alter-runtime`
 
-Python projects don't have npm's `prepare`-on-install lifecycle, so this step is manual - done once after clone and persisted in your local `.git/config`.
+Pin an exact version in downstream tooling during the alpha and read the
+CHANGELOG before upgrading.
 
 ## Related projects
 
 - [`@truealter/sdk`](https://www.npmjs.com/package/@truealter/sdk) - TypeScript
   SDK client for the public MCP server.
-- ALTER MCP endpoint - `https://mcp.truealter.com` (SSE per-`~handle` stream)
+- `~alter` MCP endpoint - `https://mcp.truealter.com` (SSE per-`~handle` stream)
   and `https://api.truealter.com/api/v1/mcp` (HTTP fallback). Both are documented
   at [truealter.com](https://truealter.com).

alter_runtime-0.4.8/alter_runtime/__init__.py

@@ -0,0 +1,10 @@
+"""~Alter Identity Runtime.
+
+The local daemon that renders your identity field across the surfaces your
+device touches. See the package README for an overview.
+"""
+
+from alter_runtime.sdk.client import AlterClient
+
+__version__ = "0.4.8"
+__all__ = ["AlterClient", "__version__"]

{alter_runtime-0.3.2 → alter_runtime-0.4.8}/alter_runtime/adapters/__init__.py

@@ -1,9 +1,9 @@
 """Local adapters - ambient-signal publishers.
 
 Adapters are the runtime's *inputs from the device itself*: they observe
-something local (git commits, CC hook invocations, shell activity) and
+something local (git commits, editor-hook invocations, shell activity) and
 publish a signal onto the ``local.signal`` topic. A separate egress producer
-(W2.2d) is responsible for POSTing those signals back to the per-handle DO
+is responsible for POSTing those signals back to the per-handle Durable Object
 ``/ingest`` endpoint so they become part of the continuous identity field.
 
 Adapters are deliberately kept simple: one file per signal source, no shared
@@ -14,6 +14,12 @@ runtime component.
 
 from alter_runtime.adapters.claude_jsonl_watcher import ClaudeJsonlWatcher
 from alter_runtime.adapters.git_watcher import GitWatcher
+from alter_runtime.adapters.weave_watcher import WeaveWatcher
 from alter_runtime.adapters.worktree_watcher import WorktreeWatcher
 
-__all__ = ["ClaudeJsonlWatcher", "GitWatcher", "WorktreeWatcher"]
+__all__ = [
+    "ClaudeJsonlWatcher",
+    "GitWatcher",
+    "WeaveWatcher",
+    "WorktreeWatcher",
+]

{alter_runtime-0.3.2 → alter_runtime-0.4.8}/alter_runtime/adapters/claude_jsonl_watcher.py

@@ -1,6 +1,7 @@
 """ClaudeJsonlWatcher - ambient token-usage adapter for Claude Code transcripts.
 
-Watches ``~/.claude/projects/<slug>/*.jsonl`` files with ``watchdog``.
+Watches the per-project ``*.jsonl`` transcript files under Claude Code's
+home projects directory with ``watchdog``.
 On modification, reads new lines from the persisted byte offset, parses each
 via the privacy-hard-stop ``parse_assistant_line`` function, and POSTs
 batches to the ALTER backend token-usage audit endpoint.
@@ -11,10 +12,9 @@ Privacy guarantee
 ``parse_assistant_line`` is the ONLY path from JSONL bytes to the wire.
 It is a strict **whitelist** parser: it constructs the output dict key-by-key
 from explicitly named fields and never spreads ``record``, ``message``, or
-``usage``. The privacy regression test (``tests/test_claude_jsonl_watcher_no_content_leak.py``)
-seeds every non-whitelisted field with a CANARY sentinel and asserts that no
-sentinel reaches the serialised output. Any change to the whitelist fails
-that test.
+``usage``. A privacy regression test seeds every non-whitelisted field with a
+CANARY sentinel and asserts that no sentinel reaches the serialised output.
+Any change to the whitelist fails that test.
 
 Allowed output keys (exact set, no extras):
 - ``session_id``           - from top-level ``sessionId``
@@ -39,8 +39,8 @@ On file rotation (on-disk size < persisted offset), the offset is reset to 0.
 Backfill
 --------
 
-On first run, every existing ``*.jsonl`` under ``~/.claude/projects/`` is
-walked and assistant events within the last 30 days are emitted in batches of
+On first run, every existing ``*.jsonl`` under the Claude Code projects
+directory is walked and assistant events within the last 30 days are emitted in batches of
 at most 500. A 5-second sleep is inserted between batches to avoid flooding
 the backend.
 
@@ -57,18 +57,17 @@ Configuration
 The adapter is opt-in: register it only when ``config.enable_claude_jsonl_watcher``
 is ``True`` (default ``False``).
 
-Decisions
----------
+Data handling
+-------------
 
-- D-IaI-1 (Identity-as-Inference): token usage is a passive aggregate with
-  k=1 (single principal machine). The inferred signal (burn-rate by model)
-  is operational telemetry, NOT psychometric inference - no clause of the
-  IaI 5-point test is triggered. Return: operator visibility.
+- The adapter collects only aggregate token-usage counts per model
+  (input, output, and cache token totals) plus the message and session
+  identifiers listed above. It never reads or transmits prompt text,
+  response text, tool calls, or any message content. The data is local
+  operational telemetry for the owning user's own visibility.
 - HTTP auth: JWT sourced from ``load_session()`` at adapter start, then
   refreshed per-POST from ``ALTER_RUNTIME_SESSION_JWT`` env var as a
-  fallback. Full auth substrate wiring (ensureFreshSession equivalent) is a
-  Wave 2 follow-up - see ``TOKEN_USAGE_AUTH_GAP`` docstring on
-  ``TokenUsageClient``.
+  fallback. See ``TokenUsageClient`` for details.
 """
 
 from __future__ import annotations
@@ -227,7 +226,7 @@ class ClaudeJsonlWatcher(Component):
         Shared :class:`EventBus` (not published to - present for Component
         symmetry and future local-signal emission).
     projects_dir:
-        Override ``~/.claude/projects/`` for testing.
+        Override the Claude Code projects directory for testing.
     """
 
     name = "claude_jsonl_watcher"
@@ -237,9 +236,12 @@ class ClaudeJsonlWatcher(Component):
         config: DaemonConfig,
         bus: EventBus,
         projects_dir: Path | None = None,
+        *,
+        session_ref: object | None = None,
     ) -> None:
         self._config = config
         self._bus = bus
+        self._session_ref = session_ref  # Optional SessionRef for live JWT read-through
         self._projects_dir = (projects_dir or CLAUDE_PROJECTS_DIR).expanduser().resolve()
         self._stop_event = asyncio.Event()
         self._loop: asyncio.AbstractEventLoop | None = None
@@ -265,11 +267,19 @@ class ClaudeJsonlWatcher(Component):
             jwt = session.jwt
 
         api_base = os.environ.get("ALTER_RUNTIME_API_BASE", "https://api.truealter.com")
+        _ref = self._session_ref
 
         def _jwt_provider() -> str | None:
-            # Prefer env-var override (for future ensureFreshSession wiring);
+            # Prefer env-var override; then live SessionRef (proactive rotation);
             # fall back to the session JWT loaded at startup.
-            return os.environ.get("ALTER_RUNTIME_SESSION_JWT") or jwt
+            env_jwt = os.environ.get("ALTER_RUNTIME_SESSION_JWT")
+            if env_jwt:
+                return env_jwt
+            if _ref is not None:
+                live = getattr(_ref, "current", None)
+                if live is not None:
+                    return getattr(live, "jwt", None)
+            return jwt
 
         self._http_client = TokenUsageClient(base_url=api_base, jwt_provider=_jwt_provider)
 
@@ -502,7 +512,7 @@ def _read_events_from_file(
 def _slug_from_path(jsonl_path: Path, projects_dir: Path) -> str:
     """Derive the project slug from the JSONL file path.
 
-    ``~/.claude/projects/<slug>/<session>.jsonl`` → ``<slug>``
+    ``<projects-dir>/<slug>/<session>.jsonl`` → ``<slug>``
     """
     try:
         relative = jsonl_path.relative_to(projects_dir)

alter_runtime-0.4.8/alter_runtime/adapters/contract.py

@@ -0,0 +1,103 @@
+"""Adapter plugin contract, the public extension seam for runtime adapters.
+
+Built-in adapters are registered directly in :mod:`alter_runtime.daemon`.
+Out-of-tree adapters (for example gated or separately-installed adapters
+kept in their own package) register under the ``alter_runtime.adapters``
+entry-point group and are discovered at start-up. This keeps the daemon
+free of any import of an adapter that lives outside the public tree: an
+adapter the host has not installed is simply absent, and the public package
+carries no reference to it.
+
+A plugin entry-point resolves to a *factory*: a callable that accepts a
+single :class:`AdapterContext` and returns one component, an iterable of
+components, or ``None`` to decline registration (for example when the
+adapter is disabled by config). A returned component is any object with an
+async ``run`` method, matching :class:`alter_runtime.daemon.Component`.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from alter_runtime.daemon import Component
+
+logger = logging.getLogger(__name__)
+
+#: Entry-point group external adapter packages register under.
+ADAPTER_ENTRY_POINT_GROUP = "alter_runtime.adapters"
+
+
+@dataclass(frozen=True)
+class AdapterContext:
+    """Stable construction context handed to every adapter factory.
+
+    Passing a context object rather than positional arguments keeps the
+    factory signature stable as the runtime gains new wiring: new fields are
+    added here without changing existing plugins.
+    """
+
+    config: Any
+    event_bus: Any
+    session: Any = None
+
+
+#: A factory takes an AdapterContext and returns component(s) or None.
+AdapterFactory = Callable[["AdapterContext"], "Component | Iterable[Component] | None"]
+
+
+def discover_adapter_components(context: AdapterContext) -> Iterator[Component]:
+    """Yield components contributed by installed adapter plugins.
+
+    Each entry-point under :data:`ADAPTER_ENTRY_POINT_GROUP` is loaded and
+    called with ``context``. Failures (import error, factory exception, a
+    non-component return) are logged and skipped so a single bad plugin can
+    never prevent the daemon from starting. When no plugin package is
+    installed the generator is empty and the daemon runs exactly as a clean
+    public build does.
+    """
+    try:
+        discovered = entry_points(group=ADAPTER_ENTRY_POINT_GROUP)
+    except Exception:  # pragma: no cover - importlib metadata edge cases
+        logger.exception("failed to enumerate adapter entry-points")
+        return
+
+    for entry_point in discovered:
+        try:
+            factory = entry_point.load()
+            result = factory(context)
+        except Exception:
+            logger.exception("adapter plugin %r failed to load; skipping", entry_point.name)
+            continue
+        if result is None:
+            continue
+        candidates = result if _is_iterable(result) else [result]
+        for component in candidates:
+            if _looks_like_component(component):
+                logger.info("registered adapter plugin component: %s", entry_point.name)
+                yield component
+            else:
+                logger.warning(
+                    "adapter plugin %r returned a non-component (%s); skipping",
+                    entry_point.name,
+                    type(component).__name__,
+                )
+
+
+def _is_iterable(obj: object) -> bool:
+    if isinstance(obj, (str, bytes)):
+        return False
+    try:
+        iter(obj)  # type: ignore[call-overload]
+    except TypeError:
+        return False
+    return True
+
+
+def _looks_like_component(obj: object) -> bool:
+    run = getattr(obj, "run", None)
+    return callable(run)