platformforge 0.1.0__py3-none-any.whl

platformforge/data/rules/catalog/security.yaml

@@ -0,0 +1,159 @@
+# DevSecOps rules — PF-SEC-*.
+rules:
+  - rule_id: PF-SEC-001
+    domain: security
+    title: "Wildcard actions or admin grant in IAM policy"
+    severity: critical
+    applies_to: {fact_kind: security.iam_policy}
+    conditions:
+      any:
+        - {path: attrs.admin_grant, op: equals, value: true}
+        - {path: attrs.wildcard_actions, op: gt, value: 0}
+    message: "* actions widen compromise to everything the role can name"
+    sources: ['aws-iam-docs']
+    source_refs:
+      aws-iam-docs: "IAM/latest/UserGuide/access_policies_manage-attach-detach.html"
+
+  - rule_id: PF-SEC-002
+    domain: security
+    title: "Public principal in IAM policy"
+    severity: critical
+    applies_to: {fact_kind: security.iam_policy}
+    conditions:
+      all:
+        - {path: attrs.public_principals, op: gt, value: 0}
+    message: "Principal '*' grants the internet access"
+    sources: ['aws-iam-docs']
+    source_refs:
+      aws-iam-docs: "IAM/latest/UserGuide/reference_policies_elements_principal.html"
+
+  - rule_id: PF-SEC-003
+    domain: security
+    title: "Wildcard resource in IAM policy"
+    severity: medium
+    applies_to: {fact_kind: security.iam_policy}
+    conditions:
+      all:
+        - {path: attrs.wildcard_resources, op: gt, value: 0}
+    message: "Resource '*' applies the grant to every object"
+    sources: ['aws-iam-docs']
+    source_refs:
+      aws-iam-docs: "IAM/latest/UserGuide/reference_policies_elements_resource.html"
+
+  - rule_id: PF-SEC-010
+    domain: security
+    title: "Secret pattern in repository file"
+    severity: critical
+    applies_to: {fact_kind: security.secret_leak}
+    conditions:
+      all:
+        - {path: attrs.hit_count, op: gt, value: 0}
+    message: "rotate first, scrub second — history retains the value"
+    sources: ['github-security-docs']
+    source_refs:
+      github-security-docs: "en/code-security/secret-scanning/about-secret-scanning"
+
+  - rule_id: PF-SEC-020
+    domain: security
+    title: "Component with known CVE (offline vuln list)"
+    severity: high
+    applies_to: {fact_kind: security.sbom}
+    conditions:
+      all:
+        - {path: attrs.vuln_count, op: gt, value: 0}
+    message: "matched against caller-supplied vuln list — freshness matters"
+    sources: ['nvd', 'osv']
+    source_refs:
+      nvd: "vuln"
+
+  - rule_id: PF-SEC-021
+    domain: security
+    title: "Component without declared license"
+    severity: low
+    applies_to: {fact_kind: security.sbom}
+    conditions:
+      all:
+        - {path: attrs.unlicensed_components, op: not_empty}
+    message: "license posture unknown — legal exposure is unbounded"
+    sources: ['spdx-licenses']
+    source_refs:
+      spdx-licenses: "licenses"
+
+  - rule_id: PF-SEC-030
+    domain: security
+    title: "Artifact image not digest-pinned"
+    severity: high
+    applies_to: {fact_kind: security.artifact}
+    conditions:
+      all:
+        - {path: attrs.digest_pinned, op: equals, value: false}
+    message: "tag references are mutable — pin sha256 digest"
+    sources: ['kubernetes-docs']
+    source_refs:
+      kubernetes-docs: "docs/concepts/containers/images#image-pull-policy"
+
+  - rule_id: PF-SEC-031
+    domain: security
+    title: "Artifact without signature attestation"
+    severity: medium
+    applies_to: {fact_kind: security.artifact}
+    conditions:
+      all:
+        - {path: attrs.signed, op: equals, value: false}
+    message: "unsigned artifacts can't prove origin (cosign/SLSA)"
+    sources: ['slsa-spec', 'sigstore-docs']
+    source_refs:
+      slsa-spec: "spec/v1.0/levels"
+
+  - rule_id: PF-SEC-040
+    domain: security
+    title: "Legacy Kyverno policy type on deprecated engine version"
+    severity: medium
+    applies_to: {fact_kind: kyverno.policy}
+    conditions:
+      all:
+        - {path: attrs.legacy_type, op: equals, value: true}
+        - {path: attrs.legacy_deprecated, op: equals, value: true}
+    message: "Policy/ClusterPolicy are deprecated on kyverno ≥1.13 — migrate to CEL-based types"
+    sources: ['kyverno-docs']
+    source_refs:
+      kyverno-docs: "docs/"
+
+  - rule_id: PF-SEC-041
+    domain: security
+    title: "Kyverno policy with no rules"
+    severity: low
+    applies_to: {fact_kind: kyverno.policy}
+    conditions:
+      all:
+        - {path: attrs.rules, op: equals, value: 0}
+        - {path: attrs.policy_kind, op: in, value: [Policy, ClusterPolicy]}
+    message: "empty ruleset enforces nothing — declared intent without effect"
+    sources: ['kyverno-docs']
+    source_refs:
+      kyverno-docs: "docs/"
+
+  - rule_id: PF-SEC-042
+    domain: security
+    title: "Signature claimed but never verified"
+    severity: high
+    applies_to: {fact_kind: supply.signature}
+    conditions:
+      all:
+        - {path: attrs.claimed_signed, op: equals, value: true}
+        - {path: attrs.verified, op: equals, value: false}
+    message: "signed=true in a document is a claim — verification needs rekor/key lookup (host boundary)"
+    sources: ['sigstore-docs']
+
+  - rule_id: PF-SEC-043
+    domain: security
+    title: "OIDC-federated principal in trust policy"
+    severity: info
+    applies_to: {fact_kind: security.iam_policy}
+    conditions:
+      all:
+        - {path: attrs.federated_providers, op: not_empty}
+    message: "web-identity federation — check audience/sub conditions on the provider"
+    sources: ['aws-iam-docs']
+    source_refs:
+      aws-iam-docs: "IAM/latest/UserGuide/id_roles_providers_oidc.html"

platformforge/data/rules/catalog/sre.yaml

@@ -0,0 +1,67 @@
+# SRE rules — operate on sre.* facts emitted by observe verbs.
+rules:
+  - rule_id: PF-SLO-001
+    domain: sre
+    title: "Error budget exhausted"
+    severity: critical
+    applies_to: {fact_kind: sre.error_budget}
+    conditions:
+      all:
+        - {path: attrs.status, op: equals, value: exhausted}
+    message: "freeze non-essential change; reliability is the feature now"
+    sources: ['google-sre-book']
+    source_refs:
+      google-sre-book: "sre-book/service-level-objectives"
+
+  - rule_id: PF-SLO-002
+    domain: sre
+    title: "Burn rate above 1 — budget consumed faster than window"
+    severity: high
+    applies_to: {fact_kind: sre.error_budget}
+    conditions:
+      all:
+        - {path: attrs.status, op: in, value: [at_risk, exhausted]}
+        - {path: attrs.burn_rate, op: gte, value: 2.0}
+    message: "sustained burn ≥2× empties the budget inside half the window"
+    sources: ['google-sre-book']
+    source_refs:
+      google-sre-book: "workbook/alerting-on-slos"
+
+  - rule_id: PF-SLO-003
+    domain: sre
+    title: "SLO inputs unresolved"
+    severity: info
+    applies_to: {fact_kind: sre.error_budget}
+    conditions:
+      all:
+        - {path: attrs.status, op: equals, value: unresolved}
+    message: "no SLI events — budget position cannot be claimed"
+    sources: ['google-sre-book']
+    source_refs:
+      google-sre-book: "sre-book/service-level-objectives"
+
+  - rule_id: PF-SRE-001
+    domain: sre
+    title: "Saturated resource"
+    severity: high
+    applies_to: {fact_kind: sre.capacity}
+    conditions:
+      all:
+        - {path: attrs.class, op: equals, value: saturated}
+    message: "≥95% utilization — headroom gone before the next spike"
+    sources: ['google-sre-book']
+    source_refs:
+      google-sre-book: "sre-book/monitoring-distributed-systems"
+
+  - rule_id: PF-SRE-002
+    domain: sre
+    title: "Hot resource"
+    severity: medium
+    applies_to: {fact_kind: sre.capacity}
+    conditions:
+      all:
+        - {path: attrs.class, op: equals, value: hot}
+    message: "≥85% utilization — plan capacity, don't wait for the page"
+    sources: ['google-sre-book']
+    source_refs:
+      google-sre-book: "workbook/implementing-slos"

platformforge/diagnose/__init__.py

@@ -0,0 +1,75 @@
+"""Compose graph + findings into a per-node diagnosis (§7 `diagnose`).
+
+Answers "o que há de errado com X?" with evidence: the node's facts, the
+findings touching it (by evidence location/source), its blast radius, and
+what remains unresolved. Never infers — absent facts stay `unresolved`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.graph.model import Graph
+from platformforge.graph.model import node_id as mk_node_id
+from platformforge.graph.query import blast_radius, dependencies, dependents
+
+
+def _fact_nodes(fact: dict) -> set[str]:
+    """Node ids a fact contributes to, via its graph contribution."""
+    out = {fact.get("attrs", {}).get("node_id") or
+           fact.get("attrs", {}).get("id")}
+    for n in ((fact.get("attrs") or {}).get("graph") or {}).get("nodes", []):
+        out.add(mk_node_id(n["kind"], n["label"]))
+    return {x for x in out if x}
+
+
+def _findings_for(findings: list[dict], node_id: str,
+                  facts_by_id: dict[str, dict]) -> list[dict]:
+    out = []
+    for f in findings:
+        for e in f.get("evidence", []):
+            fact = facts_by_id.get(e, {})
+            loc = str(fact.get("location") or fact.get("source") or "")
+            if node_id in _fact_nodes(fact) or node_id in loc \
+                    or e == node_id:
+                out.append({"rule_id": f.get("rule_id"),
+                            "severity": f.get("severity"),
+                            "title": f.get("title"),
+                            "via": e})
+                break
+    return out
+
+
+def diagnose(g: Graph, node_id: str, findings: list[dict],
+             facts: list[dict] | None = None,
+             criticality: dict | None = None) -> dict[str, Any]:
+    node = g.nodes.get(node_id)
+    if node is None:
+        return {"refusal": "platform.diagnose.unknown_node",
+                "node": node_id,
+                "unlock": "platformforge graph stats → pick a node id"}
+    facts_by_id = {f.get("fact_id"): f for f in facts or []}
+    node_facts = [f for f in facts_by_id.values()
+                  if node_id in _fact_nodes(f)
+                  or node_id in str(f.get("source", ""))]
+    blast = blast_radius(g, node_id)
+    deps = sorted(dependencies(g, node_id))
+    deps_of = sorted(dependents(g, node_id))
+
+    unresolved = []
+    for want in ("owner", "criticality", "env"):
+        if want not in node.attrs:
+            unresolved.append(f"node.attrs.{want}")
+    if node_facts == []:
+        unresolved.append("node_facts (no analyzer emitted facts for node)")
+
+    from platformforge.risk.engine import assess_change
+    from platformforge.risk.engine import criticality as crit
+    sig = {"blast_radius": len(blast.get("nodes", [])),
+           "declared_criticality": crit(node.attrs)}
+    sev = assess_change(sig)
+    return {"node": node_id, "kind": node.kind, "attrs": node.attrs,
+            "facts": node_facts,
+            "findings": _findings_for(findings, node_id, facts_by_id),
+            "dependencies": deps, "dependents": deps_of,
+            "blast_radius": blast, "risk": sev, "unresolved": unresolved}

platformforge/distribution/__init__.py

@@ -0,0 +1,18 @@
+"""Portable distribution for Platform Forge."""
+from .bundle import build_bundle, install_bundle, verify_bundle
+from .models import DistributionManifest, InstallPlan, InstallReceipt
+from .service import apply_install, doctor, plan_install, uninstall, upgrade
+
+__all__ = [
+    "DistributionManifest",
+    "InstallPlan",
+    "InstallReceipt",
+    "apply_install",
+    "build_bundle",
+    "doctor",
+    "install_bundle",
+    "plan_install",
+    "uninstall",
+    "upgrade",
+    "verify_bundle",
+]

platformforge/distribution/bundle.py

@@ -0,0 +1,127 @@
+"""Self-contained, relocatable portable bundles."""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from pathlib import Path
+
+from platformforge.distribution.service import _distribution, portable_assets
+
+
+def _sha(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+def build_bundle(output: str | Path, profile: str = "agentic",
+                 hosts: list[str] | None = None, offline: bool = True) -> dict:
+    hosts = hosts or ["agents"]
+    root = Path(output).resolve()
+    if root.exists():
+        shutil.rmtree(root)
+    root.mkdir(parents=True)
+    assets = portable_assets(hosts)
+    manifest = _distribution(profile, hosts, assets)
+    for rel, data in assets.items():
+        p = root / "assets" / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(data)
+    (root / "manifest.json").write_text(json.dumps(manifest.to_dict(), indent=2, sort_keys=True) + "\n")
+    lines = []
+    for p in sorted((root / "assets").rglob("*")):
+        if p.is_file():
+            rel = p.relative_to(root)
+            lines.append(f"{_sha(p.read_bytes())}  {rel.as_posix()}")
+    (root / "MANIFEST.sha256").write_text("\n".join(lines) + "\n")
+    return {"bundle": str(root), "distribution_id": manifest.distribution_id,
+            "assets": len(assets), "offline": offline}
+
+def verify_bundle(bundle: str | Path) -> dict:
+    root = Path(bundle).resolve()
+    mp, cp = root / "manifest.json", root / "MANIFEST.sha256"
+    if not mp.is_file() or not cp.is_file():
+        return {"valid": False, "refusal": "PF-DIST-BUNDLE-INCOMPLETE"}
+    bad = []
+    for line in cp.read_text().splitlines():
+        if not line.strip():
+            continue
+        digest, rel = line.split("  ", 1)
+        p = (root / rel).resolve()
+        if root not in p.parents:
+            bad.append(rel + ":path-escape")
+        elif not p.is_file() or _sha(p.read_bytes()) != digest:
+            bad.append(rel)
+    return {"valid": not bad, "bad": bad,
+            "refusal": None if not bad else "PF-DIST-HASH-MISMATCH"}
+
+
+def install_bundle(bundle: str | Path, target: str | Path) -> dict:
+    """Install a verified bundle without network access."""
+    import os
+
+    from platformforge.distribution.models import DIST_SCHEMA, DistributionManifest, InstallReceipt
+    from platformforge.distribution.service import DIST_MANIFEST, INSTALL_RECEIPT, PF_DIR, _safe_target, _sha
+    from platformforge.workspace.service import ensure_workspace
+
+    root = Path(bundle).resolve()
+    target = Path(target).resolve()
+    verified = verify_bundle(root)
+    if not verified["valid"]:
+        return verified
+    manifest = DistributionManifest.from_dict(json.loads((root / "manifest.json").read_text()))
+    if manifest.schema != DIST_SCHEMA:
+        return {"valid": False, "refusal": "PF-DIST-UNSUPPORTED-SCHEMA",
+                "schema": manifest.schema}
+
+    old = {}
+    rp = target / PF_DIR / INSTALL_RECEIPT
+    if rp.is_file():
+        try:
+            old = json.loads(rp.read_text()).get("files", {})
+        except (OSError, ValueError):
+            old = {}
+
+    conflicts, writes = [], []
+    for asset in manifest.assets:
+        src = (root / "assets" / asset.path).resolve()
+        if root not in src.parents or not src.is_file():
+            return {"valid": False, "refusal": "PF-DIST-BUNDLE-INCOMPLETE",
+                    "asset": asset.path}
+        dest = _safe_target(target, asset.path)
+        if dest.exists():
+            cur = _sha(dest.read_bytes())
+            if cur == asset.sha256:
+                continue
+            if old.get(asset.path) != cur:
+                conflicts.append(asset.path)
+                continue
+        writes.append((src, dest))
+    if conflicts:
+        return {"refusal": "PF-DIST-CONFLICT", "conflicts": conflicts}
+
+    staged = []
+    try:
+        for src, dest in writes:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            tmp = dest.with_name(dest.name + ".platformforge-stage")
+            tmp.write_bytes(src.read_bytes())
+            staged.append((tmp, dest))
+        for tmp, dest in staged:
+            os.replace(tmp, dest)
+        ensure_workspace(target, profile=manifest.profile, hosts=manifest.hosts)
+        pf = target / PF_DIR
+        pf.mkdir(parents=True, exist_ok=True)
+        (pf / DIST_MANIFEST).write_text(json.dumps(manifest.to_dict(), indent=2, sort_keys=True) + "\n")
+        files = {a.path: a.sha256 for a in manifest.assets}
+        receipt = InstallReceipt(
+            manifest.distribution_id, manifest.platformforge_version,
+            manifest.source_sha, str(target), manifest.profile,
+            manifest.hosts, files,
+        )
+        (pf / INSTALL_RECEIPT).write_text(json.dumps(receipt.to_dict(), indent=2, sort_keys=True) + "\n")
+        return {"status": "committed", "offline": True,
+                "distribution_id": manifest.distribution_id,
+                "files": len(files), "target": str(target)}
+    except Exception:
+        for tmp, _ in staged:
+            tmp.unlink(missing_ok=True)
+        raise

platformforge/distribution/hostflow.py

@@ -0,0 +1,247 @@
+"""``platformforge hosts`` — observe the AI host, open it when supported.
+
+Real per-host flow, every step a documented command verified against the
+installed revisions (devin 3000.x, Claude Code 2.x, codex-cli 0.160.x,
+read in 2026-10):
+
+1. detect the binary (``shutil.which``);
+2. read the version (``<bin> --version``);
+3. check authentication through the official status subcommand — the
+   receipt carries only the ``logged_in`` boolean, never the output (it
+   can list credential paths);
+4. read the repo's integration state (``install.service.status``);
+5. with ``--launch`` and a TTY, run ``<bin>`` in the repo directory — the
+   host inherits the terminal and returns its exit code to the receipt.
+   Without TTY or ``--launch``, the receipt carries ``launch_command``
+   for the operator to paste.
+
+A signed-out host is never launched: the receipt points at the official
+login command and never asks for a credential in a prompt. MCP exposes
+observation only — launching stays a CLI+TTY human boundary.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+Which = Callable[[str], str | None]
+Runner = Callable[[list[str]], tuple[int, str]]
+
+_TIMEOUT_S = 15
+_OUT_MAX = 400
+
+LOGIN_HINTS = {
+    "devin": "devin auth login",
+    "claude": "claude auth login",
+    "codex": "codex login",
+}
+
+#: Hosts the flow knows how to observe. ``copilot`` has no documented
+#: status subcommand — ``logged_in`` stays ``None`` (honest unknown).
+HOST_NAMES: tuple[str, ...] = ("claude", "devin", "codex", "copilot")
+
+
+@dataclass(frozen=True)
+class _HostCmd:
+    binary: str
+    auth_status: tuple[str, ...] | None
+
+
+_HOST_CMDS = {
+    "claude": _HostCmd("claude", ("auth", "status")),
+    "devin": _HostCmd("devin", ("auth", "status")),
+    "codex": _HostCmd("codex", ("login", "status")),
+    "copilot": _HostCmd("copilot", None),
+}
+
+
+def _default_which(binary: str) -> str | None:
+    return shutil.which(binary)
+
+
+def _default_runner(argv: list[str]) -> tuple[int, str]:
+    proc = subprocess.run(
+        argv, capture_output=True, text=True, timeout=_TIMEOUT_S,
+        errors="replace", check=False,
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+def _logged_in(host: str, out: str) -> bool | None:
+    """Only the boolean. No legible positive/negative evidence -> ``None``."""
+    if host == "claude":
+        try:
+            data = json.loads(out)
+        except ValueError:
+            data = None
+        if isinstance(data, dict) and "loggedIn" in data:
+            return bool(data["loggedIn"])
+    low = out.lower()
+    # negative before positive: "Not logged in" contains "logged in"
+    if any(s in low for s in (
+        "not logged", "logged out", "no credentials", "unauthorized",
+    )):
+        return False
+    if "logged in" in low:
+        return True
+    return None
+
+
+def _call(executable: str, argv: list[str], runner: Runner) -> tuple[int, str] | dict[str, Any]:
+    try:
+        return runner([executable, *argv])
+    except subprocess.TimeoutExpired as exc:
+        return {
+            "status": "refused",
+            "reason": "host_cli_timeout",
+            "command": " ".join(argv),
+            "timeout_s": exc.timeout,
+        }
+    except OSError as exc:
+        return {
+            "status": "refused",
+            "reason": "host_cli_failed",
+            "command": " ".join(argv),
+            "output": str(exc)[-_OUT_MAX:],
+        }
+
+
+def _integration(repo: Path) -> dict[str, Any]:
+    """Repo install state, touching nothing — ``unverified`` when never installed."""
+    try:
+        from platformforge.install import service
+
+        st = service.status(scope="project", root=repo)
+    except Exception as exc:  # noqa: BLE001 — status must never take the host flow down
+        return {"state": "unknown", "error": str(exc)[:200]}
+    return {
+        "state": st.get("status", "unknown"),
+        "checks": [
+            {"id": c.get("id"), "status": c.get("status")}
+            for c in (st.get("checks") or [])
+        ],
+    }
+
+
+def host_state(
+    host: str,
+    *,
+    repo: Path,
+    which: Which | None = None,
+    runner: Runner | None = None,
+) -> dict[str, Any]:
+    """Observed state of one host: binary, version, auth, integration, launch cmd."""
+    if host not in _HOST_CMDS:
+        return {"host": host, "state": "refused",
+                "reason": "host_unknown", "known": list(_HOST_CMDS)}
+    which = which or _default_which
+    runner = runner or _default_runner
+    cmd = _HOST_CMDS[host]
+    state: dict[str, Any] = {
+        "host": host,
+        "binary": cmd.binary,
+        "launch_command": cmd.binary,
+    }
+    path = which(cmd.binary)
+    if not path:
+        state["state"] = "NOT_DETECTED"
+        return state
+    state["binary_path"] = path
+    state["state"] = "DETECTED"
+
+    version = _call(path, ["--version"], runner)
+    if isinstance(version, dict):
+        state["version_refused"] = version
+    else:
+        rc, out = version
+        first = next(
+            (line.strip() for line in out.splitlines() if line.strip()), "")
+        state["version"] = first or None
+        state["state"] = "SUPPORTED" if rc == 0 else "DETECTED"
+
+    if cmd.auth_status is None:
+        state["logged_in"] = None
+        state["auth_note"] = "no documented status subcommand in this revision"
+    else:
+        auth = _call(path, list(cmd.auth_status), runner)
+        if isinstance(auth, dict):
+            state["auth_refused"] = auth
+            state["logged_in"] = None
+        else:
+            state["logged_in"] = _logged_in(host, auth[1])
+    if state.get("logged_in") is False:
+        state["login_hint"] = LOGIN_HINTS.get(host)
+
+    state["integration"] = _integration(repo)
+    state["state"] = _final_state(state)
+    return state
+
+
+def _final_state(state: dict[str, Any]) -> str:
+    if state.get("logged_in") is False:
+        return "NEEDS_LOGIN"
+    integ = (state.get("integration") or {}).get("state")
+    if integ == "healthy":
+        return "READY"
+    if integ in {"degraded", "broken"}:
+        return "INTEGRATION_" + integ.upper()
+    return "SUPPORTED"
+
+
+def hosts_flow(
+    target: str,
+    *,
+    repo: Path,
+    launch: bool = False,
+    tty: bool | None = None,
+    which: Which | None = None,
+    runner: Runner | None = None,
+    exec_host: Callable[[str, Path], int] | None = None,
+) -> dict[str, Any]:
+    """The host flow: implicit selector via ``target`` (``all`` measures every
+    declared host), per-host state, and a real launch when ``--launch`` +
+    TTY + READY.
+
+    ``exec_host(path, repo)`` is the launch seam — the CLI injects
+    ``subprocess.call``; a test injects a spy. Without a TTY, ``launched``
+    is false and ``launch_refused`` says why — never silence.
+    """
+    repo = Path(repo)
+    names = list(HOST_NAMES) if target == "all" else [target]
+    states = [
+        host_state(name, repo=repo, which=which, runner=runner)
+        for name in names
+    ]
+    receipt: dict[str, Any] = {
+        "repo": repo.as_posix(),
+        "hosts": states,
+        "launched": False,
+    }
+    if target == "all" or not launch:
+        if launch:
+            receipt["launch_refused"] = "selector `all` does not launch: pick one host"
+        return receipt
+
+    state = states[0]
+    tty = sys.stdin.isatty() if tty is None else tty
+    if state["state"] == "NOT_DETECTED":
+        receipt["launch_refused"] = "host_absent"
+    elif state["state"] == "NEEDS_LOGIN":
+        receipt["launch_refused"] = "login_required"
+        receipt["login_hint"] = state.get("login_hint")
+    elif not tty:
+        receipt["launch_refused"] = "no_tty"
+    else:
+        # Path came from shutil.which — same trust level as any PATH exec.
+        exec_fn = exec_host or (
+            lambda path, cwd: subprocess.call(
+                [path], cwd=str(cwd)))
+        receipt["launched"] = True
+        receipt["host_exit_code"] = exec_fn(state["binary_path"], repo)
+    return receipt