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

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

@@ -26,3 +26,14 @@ htmlcov/
 *.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.3 → alter_runtime-0.4.8}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: alter-runtime
-Version: 0.3.3
-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
@@ -111,9 +108,8 @@ filing a public issue. Non-security bugs and feature requests: email
 ## Status
 
 Shipped: the daemon and `AlterClient` SDK; subscribers, the Unix socket,
-D-Bus, and the git watcher; systemd and launchd service units; the CC hook
-and scripts integration; and the eBPF subscriber (reference implementation
-in the `alter-ebpf` package).
+D-Bus, and the git watcher; systemd and launchd service units; the local
+editor and shell hook surfaces; and the eBPF subscriber.
 
 ## Install
 
@@ -161,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.
 
@@ -170,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:
    - Git commits, branch switches, pushes (via `watchdog` on `.git/refs/heads/`)
    - 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
 
@@ -192,14 +188,14 @@ 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/
-│   │   ├── do_sse.py             # primary - subscribes to handle-alter DO SSE
+│   │   ├── do_sse.py             # primary - subscribes to the per-handle DO SSE stream
 │   │   └── mcp_fallback.py       # fallback - polls api.truealter.com/api/v1/mcp
 │   ├── sockets/
 │   │   ├── unix.py               # /run/user/$UID/alter.sock
@@ -243,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.3 → 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
@@ -43,9 +40,8 @@ filing a public issue. Non-security bugs and feature requests: email
 ## Status
 
 Shipped: the daemon and `AlterClient` SDK; subscribers, the Unix socket,
-D-Bus, and the git watcher; systemd and launchd service units; the CC hook
-and scripts integration; and the eBPF subscriber (reference implementation
-in the `alter-ebpf` package).
+D-Bus, and the git watcher; systemd and launchd service units; the local
+editor and shell hook surfaces; and the eBPF subscriber.
 
 ## Install
 
@@ -93,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.
 
@@ -102,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:
    - Git commits, branch switches, pushes (via `watchdog` on `.git/refs/heads/`)
    - 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
 
@@ -124,14 +120,14 @@ 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/
-│   │   ├── do_sse.py             # primary - subscribes to handle-alter DO SSE
+│   │   ├── do_sse.py             # primary - subscribes to the per-handle DO SSE stream
 │   │   └── mcp_fallback.py       # fallback - polls api.truealter.com/api/v1/mcp
 │   ├── sockets/
 │   │   ├── unix.py               # /run/user/$UID/alter.sock
@@ -175,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.3 → 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
@@ -17,4 +17,9 @@ 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", "WeaveWatcher", "WorktreeWatcher"]
+__all__ = [
+    "ClaudeJsonlWatcher",
+    "GitWatcher",
+    "WeaveWatcher",
+    "WorktreeWatcher",
+]

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

@@ -12,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``
@@ -58,13 +57,14 @@ Configuration
 The adapter is opt-in: register it only when ``config.enable_claude_jsonl_watcher``
 is ``True`` (default ``False``).
 
-Decisions
----------
+Data handling
+-------------
 
-- 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. See ``TokenUsageClient`` for details.
@@ -236,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
@@ -264,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)
 

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)

{alter_runtime-0.3.3 → alter_runtime-0.4.8}/alter_runtime/adapters/git_watcher.py

@@ -28,8 +28,8 @@ Signals
       }
 
 Both are published on the ``local.signal`` topic for the eventual egress
-producer. The runtime itself does *not* post them back to the DO - that is
-the egress producer's job in W2.2d.
+producer. The runtime itself does *not* post them back to the server - that
+is the egress producer's job: it consumes these signals and forwards them.
 
 Design notes
 ------------
@@ -72,12 +72,12 @@ logger = logging.getLogger("alter_runtime.adapters.git_watcher")
 
 EGRESS_TOPIC: str = "local.signal"
 
-#: Branch-name shape gate (Pentest 2026-04-26, MEDIUM). Git itself imposes
+#: Branch-name shape gate (hardening). Git itself imposes
 #: tighter rules (see ``check-ref-format(1)``), but a watchdog-driven file
 #: rename can land arbitrary bytes here if an attacker plants a malicious
 #: file under ``.git/refs/heads/``. We accept the conservative subset that
 #: covers every legitimate branch name we expect on disk and reject the
-#: rest before they reach the bus and any downstream consumers (DO ingest,
+#: rest before they reach the bus and any downstream consumers (server ingest,
 #: status-bar widgets, etc.).
 
 _BRANCH_NAME_RE = _re.compile(r"^[A-Za-z0-9_./-]+$")
@@ -221,7 +221,7 @@ class GitWatcher(Component):
         repos: list[_WatchedRepo] = []
         for path in paths:
             git_dir = path / ".git"
-            # Pentest 2026-04-26 (MEDIUM): refuse to register a watch when
+            # Hardening: refuse to register a watch when
             # ``.git`` is a symlink. Watchdog follows symlinks transparently,
             # which would let an attacker drop a symlinked .git into a CWD
             # the daemon scans and trick the watcher into observing - and
@@ -284,8 +284,8 @@ class GitWatcher(Component):
             if path == head_file or path.name == "HEAD":
                 new_branch = _read_head_branch(head_file) if head_file.exists() else None
                 if new_branch and new_branch != repo.head_branch:
-                    # Pentest 2026-04-26 (MEDIUM): branch names traverse the
-                    # bus to the DO ingest path. Reject anything that doesn't
+                    # Hardening: branch names traverse the
+                    # bus to the server ingest path. Reject anything that doesn't
                     # match the conservative shape gate before publishing -
                     # don't update head_branch on reject so the next valid
                     # change still fires.
@@ -317,7 +317,7 @@ class GitWatcher(Component):
             if not path.exists() or not path.is_file():
                 return
             branch = _branch_name_from_ref(refs_dir, path)
-            # Pentest 2026-04-26 (MEDIUM): sanitise the branch name before it
+            # Hardening: sanitise the branch name before it
             # reaches the bus. _branch_name_from_ref derives from the on-disk
             # ref filename which a same-UID attacker can plant arbitrarily.
             if not _is_safe_branch_name(branch):
@@ -394,7 +394,7 @@ class _GitRefHandler:
         # FileOpenedEvent + FileClosedNoWriteEvent for every open-and-read
         # of a watched file. ``.git/HEAD`` and the active branch ref are
         # opened thousands of times per second by ``git status`` callers
-        # (IDE git plugins, statusline scripts, parallel CC sessions), and
+        # (IDE git plugins, statusline scripts, parallel editor/tooling sessions), and
         # without this filter every read scheduled an ``asyncio.create_task``
         # via ``_on_ref_change`` - flooding the loop with no-op handles
         # that grew RSS by ~10MB/s and tripped OOM in <5min on a busy repo.