commensa 0.1.0rc2__tar.gz

commensa-0.1.0rc2/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: commensa
+Version: 0.1.0rc2
+Summary: Verified installer and stable command router for Commensa
+Author: Commensa LLC
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://commensa.ai/
+Project-URL: Documentation, https://commensa.ai/docs
+Project-URL: Installation, https://commensa.ai/install
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Commensa bootstrap
+
+This small public package installs verified Commensa releases and keeps one
+stable `commensa` command in front of them. It does not contain the private
+Report, Cockpit, Project X-Ray, commensa me tracking, or Commensa Manager
+runtimes.
+
+Install the free Core:
+
+```bash
+pipx install commensa
+commensa install core
+```
+
+After purchasing an entitled product on `commensa.ai`, install the matching
+capability. Commensa privately asks first for the secure access link in the
+delivery email, then for the activation key. Neither belongs in a shell command.
+
+```bash
+commensa install report
+commensa install cockpit
+commensa install xray
+commensa install me
+```
+
+For example, a new Report customer can use one shell line:
+
+```bash
+pipx install commensa && commensa install report
+```
+
+Approved Manager beta operators can install Manager into selected AI
+interfaces:
+
+```bash
+commensa install manager --interface codex --interface claude-code
+```
+
+Normal product commands continue through the verified local runtime:
+
+```bash
+commensa capabilities --json
+commensa privacy --json
+commensa doctor --json
+```
+
+## Current platform boundary
+
+The release candidate supports the same command-line installation flow on
+macOS, Linux, and native Windows 11. On Windows, `pipx` supplies the isolated
+Python runtime and Commensa creates managed `.cmd` launchers; PowerShell or
+Command Prompt can run the same `commensa install ...` commands. WSL remains a
+separate Linux route.
+
+The Windows route has automated contract coverage but still requires its first
+acceptance pass on a physical Windows 11 x64 host before it can be described as
+host-verified. It is not the separately signed Windows desktop installer.
+
+Signed native installers remain the intended nontechnical customer route. This
+package is the interim cross-platform command-line route.

commensa-0.1.0rc2/README.md

@@ -0,0 +1,60 @@
+# Commensa bootstrap
+
+This small public package installs verified Commensa releases and keeps one
+stable `commensa` command in front of them. It does not contain the private
+Report, Cockpit, Project X-Ray, commensa me tracking, or Commensa Manager
+runtimes.
+
+Install the free Core:
+
+```bash
+pipx install commensa
+commensa install core
+```
+
+After purchasing an entitled product on `commensa.ai`, install the matching
+capability. Commensa privately asks first for the secure access link in the
+delivery email, then for the activation key. Neither belongs in a shell command.
+
+```bash
+commensa install report
+commensa install cockpit
+commensa install xray
+commensa install me
+```
+
+For example, a new Report customer can use one shell line:
+
+```bash
+pipx install commensa && commensa install report
+```
+
+Approved Manager beta operators can install Manager into selected AI
+interfaces:
+
+```bash
+commensa install manager --interface codex --interface claude-code
+```
+
+Normal product commands continue through the verified local runtime:
+
+```bash
+commensa capabilities --json
+commensa privacy --json
+commensa doctor --json
+```
+
+## Current platform boundary
+
+The release candidate supports the same command-line installation flow on
+macOS, Linux, and native Windows 11. On Windows, `pipx` supplies the isolated
+Python runtime and Commensa creates managed `.cmd` launchers; PowerShell or
+Command Prompt can run the same `commensa install ...` commands. WSL remains a
+separate Linux route.
+
+The Windows route has automated contract coverage but still requires its first
+acceptance pass on a physical Windows 11 x64 host before it can be described as
+host-verified. It is not the separately signed Windows desktop installer.
+
+Signed native installers remain the intended nontechnical customer route. This
+package is the interim cross-platform command-line route.

commensa-0.1.0rc2/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "commensa"
+version = "0.1.0rc2"
+description = "Verified installer and stable command router for Commensa"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+authors = [{name = "Commensa LLC"}]
+license = "LicenseRef-Proprietary"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows :: Windows 11",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://commensa.ai/"
+Documentation = "https://commensa.ai/docs"
+Installation = "https://commensa.ai/install"
+
+[project.scripts]
+commensa = "commensa_bootstrap.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["commensa_bootstrap"]

commensa-0.1.0rc2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

commensa-0.1.0rc2/src/commensa.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: commensa
+Version: 0.1.0rc2
+Summary: Verified installer and stable command router for Commensa
+Author: Commensa LLC
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://commensa.ai/
+Project-URL: Documentation, https://commensa.ai/docs
+Project-URL: Installation, https://commensa.ai/install
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Commensa bootstrap
+
+This small public package installs verified Commensa releases and keeps one
+stable `commensa` command in front of them. It does not contain the private
+Report, Cockpit, Project X-Ray, commensa me tracking, or Commensa Manager
+runtimes.
+
+Install the free Core:
+
+```bash
+pipx install commensa
+commensa install core
+```
+
+After purchasing an entitled product on `commensa.ai`, install the matching
+capability. Commensa privately asks first for the secure access link in the
+delivery email, then for the activation key. Neither belongs in a shell command.
+
+```bash
+commensa install report
+commensa install cockpit
+commensa install xray
+commensa install me
+```
+
+For example, a new Report customer can use one shell line:
+
+```bash
+pipx install commensa && commensa install report
+```
+
+Approved Manager beta operators can install Manager into selected AI
+interfaces:
+
+```bash
+commensa install manager --interface codex --interface claude-code
+```
+
+Normal product commands continue through the verified local runtime:
+
+```bash
+commensa capabilities --json
+commensa privacy --json
+commensa doctor --json
+```
+
+## Current platform boundary
+
+The release candidate supports the same command-line installation flow on
+macOS, Linux, and native Windows 11. On Windows, `pipx` supplies the isolated
+Python runtime and Commensa creates managed `.cmd` launchers; PowerShell or
+Command Prompt can run the same `commensa install ...` commands. WSL remains a
+separate Linux route.
+
+The Windows route has automated contract coverage but still requires its first
+acceptance pass on a physical Windows 11 x64 host before it can be described as
+host-verified. It is not the separately signed Windows desktop installer.
+
+Signed native installers remain the intended nontechnical customer route. This
+package is the interim cross-platform command-line route.

commensa-0.1.0rc2/src/commensa.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/commensa.egg-info/PKG-INFO
+src/commensa.egg-info/SOURCES.txt
+src/commensa.egg-info/dependency_links.txt
+src/commensa.egg-info/entry_points.txt
+src/commensa.egg-info/top_level.txt
+src/commensa_bootstrap/__init__.py
+src/commensa_bootstrap/cli.py
+src/commensa_bootstrap/errors.py
+src/commensa_bootstrap/install.py
+src/commensa_bootstrap/runtime.py

commensa-0.1.0rc2/src/commensa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

commensa-0.1.0rc2/src/commensa.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commensa = commensa_bootstrap.cli:main

commensa-0.1.0rc2/src/commensa.egg-info/top_level.txt

@@ -0,0 +1 @@
+commensa_bootstrap

commensa-0.1.0rc2/src/commensa_bootstrap/__init__.py

@@ -0,0 +1,3 @@
+"""Public Commensa installer and stable command router."""
+
+__version__ = "0.1.0rc2"

commensa-0.1.0rc2/src/commensa_bootstrap/cli.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .errors import BootstrapError
+from .install import PAID_TARGETS, connect, install
+from .runtime import forward
+
+
+INSTALL_TARGETS = ("core", *PAID_TARGETS, "manager")
+INTERFACES = ("codex", "claude-code", "cursor")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="commensa",
+        description="Install and run verified Commensa products.",
+    )
+    parser.add_argument("--version", action="version", version=f"Commensa bootstrap {__version__}")
+    sub = parser.add_subparsers(dest="bootstrap_command")
+    install_parser = sub.add_parser("install", help="install an entitled Commensa capability")
+    install_parser.add_argument("target", choices=INSTALL_TARGETS)
+    install_parser.add_argument(
+        "--interface",
+        action="append",
+        choices=INTERFACES,
+        default=[],
+        help="AI interface for Manager; repeat to install more than one",
+    )
+    connect_parser = sub.add_parser("connect", help="connect an installed runtime to an AI host")
+    connect_parser.add_argument("host", choices=INTERFACES)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments:
+        build_parser().print_help()
+        return 0
+    if arguments[0] not in {"install", "connect", "-h", "--help", "--version"}:
+        try:
+            return forward(arguments)
+        except BootstrapError as exc:
+            print(f"Commensa: {exc}", file=sys.stderr)
+            return 4
+    parser = build_parser()
+    args = parser.parse_args(arguments)
+    if args.bootstrap_command is None:
+        return 0
+    try:
+        if args.bootstrap_command == "install":
+            if args.interface and args.target != "manager":
+                raise BootstrapError("--interface applies only to Commensa Manager.")
+            install(args.target, interfaces=tuple(dict.fromkeys(args.interface)))
+            print(f"Commensa {args.target} installation and verification completed.")
+        else:
+            connect(args.host)
+            print(f"Commensa connection to {args.host} completed.")
+        return 0
+    except BootstrapError as exc:
+        print(f"Commensa: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("Commensa: cancelled.", file=sys.stderr)
+        return 7
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

commensa-0.1.0rc2/src/commensa_bootstrap/errors.py

@@ -0,0 +1,3 @@
+class BootstrapError(RuntimeError):
+    """A bounded, user-actionable bootstrap failure."""
+

commensa-0.1.0rc2/src/commensa_bootstrap/install.py

@@ -0,0 +1,416 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import getpass
+import json
+import os
+import platform
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.parse
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from .errors import BootstrapError
+from .runtime import command_invocation, default_data_home, managed_bin, runtime_command
+
+
+MAX_INSTALLER_BYTES = 512 * 1024
+MAX_ADAPTER_BYTES = 25 * 1024 * 1024
+MAX_RELEASE_BYTES = 500 * 1024 * 1024
+MAX_MANIFEST_BYTES = 32 * 1024
+USER_AGENT = "Commensa-PyPI-Bootstrap/0.1.0rc2"
+
+
+@dataclass(frozen=True)
+class InstallerSource:
+    url: str
+    sha256: str
+
+
+INSTALLERS = {
+    "core": InstallerSource(
+        "https://commensa.ai/dl/install_core.py",
+        "7cf4874a58ec33baca149cfa67ebdf07f466c6db82c675409986ebfcd9900b17",
+    ),
+    "paid": InstallerSource(
+        "https://commensa.ai/downloads/install_product.py",
+        "d8c53a1cc0f897a28c7696a60ef8b4ad3f092d16c94658777b75f845f8095f7e",
+    ),
+    "manager": InstallerSource(
+        "https://commensa.ai/downloads/install_manager.py",
+        "59081156470cb59b156fa323ca4aa86b69727ae1efb15d370d5caf1ef5b581a7",
+    ),
+}
+
+CODEX_ADAPTER = InstallerSource(
+    "https://commensa.ai/dl/adapters/commensa-codex.zip",
+    "7188ce681249f51cc295657c807b89b97cdfe34ceed4ac35a7f06860641e9c74",
+)
+
+RELEASE_MANIFESTS = {
+    "paid": "https://commensa.ai/downloads/release-manifest.json",
+    "manager": "https://commensa.ai/downloads/manager-manifest.json",
+}
+
+PAID_TARGETS = {
+    "xray": "xray_project",
+    "report": "run_report",
+    "cockpit": "open_cockpit",
+    "me": "track_me",
+}
+
+
+def _validate_source(source: InstallerSource) -> None:
+    try:
+        parsed = urllib.parse.urlsplit(source.url)
+        port = parsed.port
+    except ValueError as exc:
+        raise BootstrapError("Bootstrap download URL is invalid.") from exc
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname != "commensa.ai"
+        or parsed.username
+        or parsed.password
+        or port
+    ):
+        raise BootstrapError("Bootstrap downloads must use the Commensa HTTPS origin.")
+    if not re.fullmatch(r"[0-9a-f]{64}", source.sha256):
+        raise BootstrapError("Bootstrap source has an invalid pinned SHA-256 value.")
+
+
+def parse_access_link(link: str, *, target: str) -> tuple[str, str]:
+    try:
+        parsed = urllib.parse.urlsplit(link.strip())
+        port = parsed.port
+    except ValueError as exc:
+        raise BootstrapError("The secure Commensa access link is invalid.") from exc
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname != "commensa.ai"
+        or parsed.username
+        or parsed.password
+        or port
+    ):
+        raise BootstrapError("Use the secure https://commensa.ai access link from your delivery email.")
+    allowed_paths = {"/thanks"}
+    allowed_grants = ("session_id",)
+    if target == "manager":
+        allowed_paths.add("/manager-access")
+        allowed_grants = ("session_id", "beta_token")
+    if parsed.path not in allowed_paths:
+        raise BootstrapError("The secure access link has an unexpected Commensa path.")
+    query = urllib.parse.parse_qs(parsed.query, keep_blank_values=True)
+    present = [(name, query[name]) for name in allowed_grants if name in query]
+    if len(present) != 1 or len(present[0][1]) != 1:
+        raise BootstrapError("The secure access link is missing one valid delivery grant.")
+    name, values = present[0]
+    value = values[0]
+    if not re.fullmatch(r"[A-Za-z0-9_-]{8,512}", value):
+        raise BootstrapError("The secure access link contains an invalid delivery grant.")
+    return name, value
+
+
+def authorized_url(url: str, grant: tuple[str, str]) -> str:
+    try:
+        parsed = urllib.parse.urlsplit(url)
+        port = parsed.port
+    except ValueError as exc:
+        raise BootstrapError("Entitled download URL is invalid.") from exc
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname != "commensa.ai"
+        or parsed.username
+        or parsed.password
+        or port
+        or parsed.query
+    ):
+        raise BootstrapError("Entitled downloads must use a clean Commensa HTTPS URL.")
+    name, value = grant
+    if name not in {"session_id", "beta_token"}:
+        raise BootstrapError("Unknown Commensa delivery grant type.")
+    return urllib.parse.urlunsplit(
+        (parsed.scheme, parsed.netloc, parsed.path, urllib.parse.urlencode({name: value}), "")
+    )
+
+
+def download_verified(
+    source: InstallerSource,
+    destination: Path,
+    *,
+    maximum_bytes: int = MAX_INSTALLER_BYTES,
+) -> None:
+    _validate_source(source)
+    request = urllib.request.Request(
+        source.url,
+        headers={"accept": "application/octet-stream", "user-agent": USER_AGENT},
+    )
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = destination.with_name(f".{destination.name}.download")
+    digest = hashlib.sha256()
+    total = 0
+    try:
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response, temporary.open("wb") as handle:
+                while True:
+                    chunk = response.read(64 * 1024)
+                    if not chunk:
+                        break
+                    total += len(chunk)
+                    if total > maximum_bytes:
+                        raise BootstrapError("Verified download exceeds its size limit.")
+                    digest.update(chunk)
+                    handle.write(chunk)
+                handle.flush()
+                os.fsync(handle.fileno())
+        except (urllib.error.URLError, TimeoutError):
+            raise BootstrapError(
+                "The Commensa download could not be authorized or reached. "
+                "Reopen the secure access link or check the network, then try again."
+            ) from None
+        if not hmac.compare_digest(digest.hexdigest(), source.sha256):
+            raise BootstrapError("Downloaded Commensa installer did not match its pinned SHA-256 value.")
+        os.replace(temporary, destination)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def _installer_kind(target: str) -> str:
+    if target == "core":
+        return "core"
+    if target == "manager":
+        return "manager"
+    if target in PAID_TARGETS:
+        return "paid"
+    raise BootstrapError(f"Unknown Commensa install target: {target}")
+
+
+def build_installer_command(
+    target: str,
+    script: Path,
+    data_home: Path,
+    *,
+    interfaces: Sequence[str],
+    archive: Path | None = None,
+    archive_sha256: str | None = None,
+    version: str | None = None,
+) -> list[str]:
+    kind = _installer_kind(target)
+    command = [
+        sys.executable,
+        str(script),
+        "--python-executable",
+        sys.executable,
+        "--install-root",
+        str(data_home),
+        "--bin-dir",
+        str(managed_bin(data_home)),
+    ]
+    if kind == "manager":
+        for interface in interfaces:
+            command.extend(["--platform", interface])
+    if archive is not None:
+        if not archive_sha256 or not version:
+            raise BootstrapError("A local release archive requires its exact hash and version.")
+        command.extend(
+            [
+                "--archive",
+                str(archive),
+                "--sha256",
+                archive_sha256,
+                "--version",
+                version,
+            ]
+        )
+    return command
+
+
+def _fetch_entitled_release(
+    kind: str,
+    grant: tuple[str, str],
+    directory: Path,
+) -> tuple[Path, str, str]:
+    manifest_url = authorized_url(RELEASE_MANIFESTS[kind], grant)
+    request = urllib.request.Request(
+        manifest_url,
+        headers={"accept": "application/json", "user-agent": USER_AGENT},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            raw = response.read(MAX_MANIFEST_BYTES + 1)
+    except (urllib.error.URLError, TimeoutError):
+        raise BootstrapError(
+            "The entitled release manifest could not be authorized or reached. "
+            "Reopen the secure access link, then try again."
+        ) from None
+    if len(raw) > MAX_MANIFEST_BYTES:
+        raise BootstrapError("Commensa release manifest exceeds its size limit.")
+    try:
+        manifest = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise BootstrapError("Commensa release manifest is not valid JSON.") from exc
+    if not isinstance(manifest, dict) or manifest.get("schema_version") != "1":
+        raise BootstrapError("Commensa release manifest schema is unsupported.")
+    for field in ("archive", "sha256", "version"):
+        if not isinstance(manifest.get(field), str):
+            raise BootstrapError(f"Commensa release manifest is missing {field}.")
+    if not re.fullmatch(r"[0-9a-f]{64}", manifest["sha256"]):
+        raise BootstrapError("Commensa release manifest has an invalid archive hash.")
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,39}", manifest["version"]):
+        raise BootstrapError("Commensa release manifest has an invalid version.")
+    archive_base = urllib.parse.urljoin(RELEASE_MANIFESTS[kind], manifest["archive"])
+    try:
+        archive_parsed = urllib.parse.urlsplit(archive_base)
+        archive_port = archive_parsed.port
+    except ValueError as exc:
+        raise BootstrapError("Commensa release archive URL is invalid.") from exc
+    if (
+        archive_parsed.scheme != "https"
+        or archive_parsed.hostname != "commensa.ai"
+        or archive_parsed.username
+        or archive_parsed.password
+        or archive_port
+    ):
+        raise BootstrapError("Commensa release archive is outside the approved origin.")
+    archive = directory / Path(archive_parsed.path).name
+    download_verified(
+        InstallerSource(authorized_url(archive_base, grant), manifest["sha256"]),
+        archive,
+        maximum_bytes=MAX_RELEASE_BYTES,
+    )
+    return archive, manifest["sha256"], manifest["version"]
+
+
+def _read_json_command(command: list[str]) -> dict:
+    completed = subprocess.run(command, check=False, capture_output=True, text=True)
+    if completed.returncode not in {0, 8}:
+        raise BootstrapError("Commensa installed, but its verification command failed.")
+    try:
+        result = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise BootstrapError("Commensa installed, but verification returned invalid output.") from exc
+    if not isinstance(result, dict):
+        raise BootstrapError("Commensa verification returned an invalid response.")
+    return result
+
+
+def _verify_install(target: str, data_home: Path, system: str) -> None:
+    manager = target == "manager"
+    command = runtime_command(data_home=data_home, manager=manager, system=system)
+    if not command.is_file():
+        raise BootstrapError("Installer completed without creating the managed Commensa runtime command.")
+    if manager:
+        result = _read_json_command(
+            command_invocation(command, ["doctor", "--json"], system=system)
+        )
+        if result.get("status") not in {"ok", "needs_attention"}:
+            raise BootstrapError("Commensa Manager did not return a valid post-install status.")
+        return
+    result = _read_json_command(
+        command_invocation(command, ["capabilities", "--json"], system=system)
+    )
+    if result.get("status") != "ok" or not isinstance(result.get("capabilities"), dict):
+        raise BootstrapError("Commensa did not return its installed capability catalog.")
+    capability = PAID_TARGETS.get(target)
+    if capability and result["capabilities"].get(capability, {}).get("status") not in {
+        "available",
+        "offline_grace",
+    }:
+        raise BootstrapError(
+            f"The runtime installed, but this access key does not currently grant {target}."
+        )
+
+
+def install(
+    target: str,
+    *,
+    data_home: Path | None = None,
+    interfaces: Sequence[str] = (),
+    system: str | None = None,
+    access_link: str | None = None,
+) -> None:
+    system = system or platform.system()
+    if system not in {"Darwin", "Linux", "Windows"}:
+        raise BootstrapError(f"This Commensa bootstrap has not been accepted on {system}.")
+    kind = _installer_kind(target)
+    source = INSTALLERS[kind]
+    root = data_home or default_data_home(system)
+    root.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        os.chmod(root, 0o700)
+    except OSError:
+        pass
+    with tempfile.TemporaryDirectory(prefix=".bootstrap-", dir=root) as raw:
+        script = Path(raw) / f"install_{kind}.py"
+        archive = None
+        archive_sha256 = None
+        version = None
+        if kind == "core":
+            download_verified(source, script)
+        else:
+            link = access_link or getpass.getpass(
+                "Secure Commensa access link from your delivery email: "
+            )
+            grant = parse_access_link(link, target=target)
+            download_verified(
+                InstallerSource(authorized_url(source.url, grant), source.sha256),
+                script,
+            )
+            archive, archive_sha256, version = _fetch_entitled_release(
+                kind, grant, Path(raw)
+            )
+        command = build_installer_command(
+            target,
+            script,
+            root,
+            interfaces=interfaces,
+            archive=archive,
+            archive_sha256=archive_sha256,
+            version=version,
+        )
+        completed = subprocess.run(command, check=False)
+        if completed.returncode != 0:
+            raise BootstrapError(f"The verified Commensa {target} installer did not complete.")
+    _verify_install(target, root, system)
+
+
+def connect(host: str, *, data_home: Path | None = None, system: str | None = None) -> None:
+    system = system or platform.system()
+    root = data_home or default_data_home(system)
+    if host != "codex":
+        raise BootstrapError(
+            f"Automated {host} connection is not yet an accepted PyPI route. "
+            "Use https://commensa.ai/install for the current instructions."
+        )
+    command = runtime_command(data_home=root, system=system)
+    if not command.is_file():
+        raise BootstrapError("Install Commensa Core before connecting Codex.")
+    with tempfile.TemporaryDirectory(prefix=".adapter-", dir=root) as raw:
+        archive = Path(raw) / "commensa-codex.zip"
+        download_verified(CODEX_ADAPTER, archive, maximum_bytes=MAX_ADAPTER_BYTES)
+        completed = subprocess.run(
+            command_invocation(
+                command,
+                [
+                    "integrate",
+                    "codex",
+                    "--archive",
+                    str(archive),
+                    "--sha256",
+                    CODEX_ADAPTER.sha256,
+                ],
+                system=system,
+            ),
+            check=False,
+        )
+        if completed.returncode != 0:
+            raise BootstrapError("The verified Codex connection needs attention.")

commensa-0.1.0rc2/src/commensa_bootstrap/runtime.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+from pathlib import Path
+from typing import Sequence
+
+from .errors import BootstrapError
+
+
+def default_data_home(system: str | None = None) -> Path:
+    system = system or platform.system()
+    configured = os.environ.get("COMMENSA_HOME")
+    if configured:
+        return Path(configured).expanduser()
+    if system == "Windows":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            return Path(local) / "Commensa"
+    return Path.home() / ".commensa"
+
+
+def managed_bin(data_home: Path) -> Path:
+    return data_home.expanduser() / "bootstrap" / "bin"
+
+
+def runtime_command(
+    *,
+    data_home: Path,
+    manager: bool = False,
+    system: str | None = None,
+) -> Path:
+    system = system or platform.system()
+    name = "commensa-manager" if manager else "commensa"
+    if system == "Windows":
+        name += ".cmd"
+    return managed_bin(data_home) / name
+
+
+def command_invocation(
+    command: Path,
+    arguments: Sequence[str],
+    *,
+    system: str | None = None,
+) -> list[str]:
+    system = system or platform.system()
+    if system == "Windows":
+        return [
+            os.environ.get("COMSPEC", "cmd.exe"),
+            "/d",
+            "/s",
+            "/c",
+            str(command),
+            *arguments,
+        ]
+    return [str(command), *arguments]
+
+
+def forward(
+    arguments: Sequence[str],
+    *,
+    data_home: Path | None = None,
+    system: str | None = None,
+) -> int:
+    data_home = data_home or default_data_home(system)
+    args = list(arguments)
+    manager = bool(args and args[0] == "manager")
+    if manager:
+        args = args[1:]
+    command = runtime_command(data_home=data_home, manager=manager, system=system)
+    if not command.is_file():
+        target = "manager" if manager else "core"
+        raise BootstrapError(
+            f"The verified Commensa {target} runtime is not installed. "
+            f"Run: commensa install {target}"
+        )
+    return subprocess.run(
+        command_invocation(command, args, system=system),
+        check=False,
+    ).returncode