killchain 0.1.0__py3-none-any.whl

killchain/__init__.py

@@ -0,0 +1,10 @@
+"""killchain: split a build so a frontier agent never sees the risky half.
+
+The prompt is partitioned by *refusal risk*, not confidentiality. Anything a
+commercial coding agent would refuse, hedge, simplify, or guess at is routed to
+an abliterated orchestrator model, which then implements it locally. A frontier
+agent (Claude Code, Codex) builds the rest against stubs.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

killchain/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m killchain`."""
+from killchain.harness import main
+
+if __name__ == "__main__":
+    main()

killchain/config.toml

@@ -0,0 +1,78 @@
+# killchain configuration. Paths may use ~.
+#
+# This file is the shipped default. On first run it is copied to
+# ~/.config/killchain/config.toml, which is what you should edit.
+
+[orchestrator]
+# The abliterated orchestrator model: the only model that sees the full prompt.
+# Any OpenAI-compatible chat endpoint. Default: refuseless, settings mirrored
+# from ~/.hermes/config.yaml. The key is read from $REFUSELESS_API_KEY, or
+# from env_file if that is unset. It is never written to disk by killchain.
+base_url = "https://api.refuseless.com/v1"
+model = "deepseek-v4.1-flash-abliterated"   # also: glm-5.3-abliterated, glm-5.3-flash-abliterated
+api_key_env = "REFUSELESS_API_KEY"
+env_file = "~/.hermes/.env"
+timeout = 900
+max_partition_tries = 4
+max_impl_tries = 4
+
+[frontier]
+backend = "claude"            # claude | codex | fake
+claude_model = ""             # blank = CLI default
+claude_extra_args = ["--dangerously-skip-permissions"]  # it runs confined to the public dir
+codex_model = ""
+codex_extra_args = ["--full-auto"]
+timeout = 3600
+
+[risk]
+# Jev (TypeSafe) via the OpenRouter Decisions API. Scores each span of the
+# candidate public view on every refusal dimension in routing.py. Everything
+# scored is sent to OpenRouter, so scoring happens on the public view and, if
+# score_raw_prompt is on, on spans of the raw prompt.
+enabled = true
+base_url = "https://openrouter.ai/api/alpha/decisions"
+model = "typesafe/jev-1.14"
+api_key_env = "OPENROUTER_API_KEY"
+# Dimensions, thresholds and the per-span decision live in routing.py.
+timeout = 60
+# Pre-score the RAW PROMPT span by span to build the risk map, and let the
+# orchestrator ask for extra probes on subsets. Refusal risk is carried by the
+# original phrasing, so this is the useful mode. All of it goes to
+# OpenRouter/TypeSafe; turn off to score only the assembled public view.
+probe_raw_prompt = true
+max_probe_rounds = 3
+
+[routing]
+# Shipped defaults live in killchain/routing.py; anything set here wins. Read
+# routing.py first - these change what the frontier model is allowed to build.
+# Nothing here is required; the section exists so retuning needs no code edit.
+
+# Drop a dimension entirely (it stops being asked and stops routing spans).
+# disabled_dimensions = ["hedge_framing"]
+
+# Per-dimension bar, 0..1: the risk probability needed to pull a span out of
+# the public view. Lower = more paranoid (more goes private).
+# Valid keys: attribution, reverse_engineering, offensive_security, extraction,
+#             regulated, proprietary_model, hedge_framing, scale_or_scope,
+#             overall, default
+# [routing.thresholds]
+# hedge_framing = 0.75
+# attribution = 0.40
+
+# Adjustment per span kind, added to the bar. Fixtures are bare JSON numbers
+# and score near 0.5 whatever they contain, so they get a higher bar.
+# [routing.kind_slack]
+# fixture = 0.15
+
+# Extra regexes that block an outbound view outright, no model involved.
+# Prefix with re: for a regex, otherwise it is a literal. Prefer the denylist
+# file for terms; use this for patterns that should ship with your team's config.
+# hard_rules = ["TICKER-[A-Z]{4}", { pattern = "re:\\bsk-[a-z0-9]{20,}", why = "looks like an API key" }]
+
+[paths]
+# Defaults are user directories so an installed command never writes into
+# site-packages. Override with env vars (KILLCHAIN_PRIVATE_ROOT) or per run
+# with --workspace / --private-root. Relative paths resolve against the cwd.
+workspace = ""                    # blank = <project>/.killchain/workspace, else ~/.local/share/killchain/workspace
+private_root = "~/killchain-private"   # mode 0700: prompts, contracts, private impls
+denylist = ""                     # blank = ~/.config/killchain/denylist.txt

killchain/contract.py

@@ -0,0 +1,154 @@
+"""Contract: the agreed interface between the public (frontier-built) half and
+the private (abliterated-model-built) half of a system.
+
+The private half exists because the frontier may refuse, hedge, simplify, or
+guess at the risky parts. The contract is produced by the LOCAL model from the
+user's full prompt. Only `Contract.public_view()` ever leaves the machine;
+`private_notes` and the original prompt never do.
+
+Public fixtures are decoys on purpose: shape without behaviour. A handful of
+correct input/output points is enough for a reader to fit a rule, and a
+reverse-engineered rule is one the frontier no longer needs to have been told.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+IDENT = re.compile(r"^[a-z_][a-z0-9_]*$")
+
+
+class ContractError(ValueError):
+    pass
+
+
+@dataclass
+class Param:
+    name: str
+    type: str
+    description: str = ""
+
+
+@dataclass
+class Fixture:
+    inputs: dict[str, Any]
+    output: Any
+    note: str = ""
+
+
+@dataclass
+class Interface:
+    module: str
+    function: str
+    description: str
+    params: list[Param]
+    returns: str
+    fixtures: list[Fixture]                                  # PUBLIC decoys: shape only
+    private_fixtures: list[Fixture] = field(default_factory=list)  # real behaviour, never leaves
+
+
+@dataclass
+class Contract:
+    public_brief: str
+    interfaces: list[Interface]
+    private_notes: str = ""  # NEVER leaves the machine
+    private_plan: str = ""   # NEVER leaves the machine
+
+    # ---- construction -------------------------------------------------
+    @staticmethod
+    def from_dict(d: dict) -> "Contract":
+        try:
+            ifaces = []
+            for i in d.get("interfaces", []):
+                params = [Param(**p) for p in i.get("params", [])]
+                fixtures = [Fixture(**f) for f in i.get("fixtures", [])]
+                pfix = [Fixture(**f) for f in i.get("private_fixtures", [])]
+                ifaces.append(Interface(
+                    module=i["module"], function=i["function"],
+                    description=i.get("description", ""),
+                    params=params, returns=i.get("returns", "Any"),
+                    fixtures=fixtures, private_fixtures=pfix,
+                ))
+            return Contract(
+                public_brief=d["public_brief"], interfaces=ifaces,
+                private_notes=d.get("private_notes", ""),
+                private_plan=d.get("private_plan", ""),
+            )
+        except (KeyError, TypeError) as e:
+            raise ContractError(f"malformed contract: {e}") from e
+
+    @staticmethod
+    def from_json(s: str) -> "Contract":
+        return Contract.from_dict(json.loads(s))
+
+    # ---- validation ---------------------------------------------------
+    def validate(self) -> None:
+        if not self.public_brief.strip():
+            raise ContractError("public_brief is empty")
+        if not self.interfaces:
+            raise ContractError("contract has no interfaces; nothing is risky, "
+                                "so there is nothing to partition")
+        seen = set()
+        for i in self.interfaces:
+            for ident in (i.module, i.function):
+                if not IDENT.match(ident):
+                    raise ContractError(f"bad identifier {ident!r} (snake_case only)")
+            key = (i.module, i.function)
+            if key in seen:
+                raise ContractError(f"duplicate interface {i.module}.{i.function}")
+            seen.add(key)
+            if not i.fixtures:
+                raise ContractError(f"{i.module}.{i.function} has no public fixtures; "
+                                    "every interface needs at least one synthetic decoy example")
+            if not i.private_fixtures:
+                raise ContractError(f"{i.module}.{i.function} has no private_fixtures; "
+                                    "every interface needs at least one real example for conformance")
+            pnames = {p.name for p in i.params}
+            for p in i.params:
+                if not IDENT.match(p.name):
+                    raise ContractError(f"bad param name {p.name!r} in {i.function}")
+            for kind, fixtures in (("fixture", i.fixtures), ("private_fixture", i.private_fixtures)):
+                for n, f in enumerate(fixtures):
+                    extra = set(f.inputs) - pnames
+                    missing = pnames - set(f.inputs)
+                    if extra or missing:
+                        raise ContractError(
+                            f"{kind} {n} of {i.module}.{i.function} inputs mismatch params: "
+                            f"extra={sorted(extra)} missing={sorted(missing)}")
+                    try:
+                        json.dumps(f.inputs); json.dumps(f.output)
+                    except TypeError as e:
+                        raise ContractError(f"{kind} {n} of {i.function} not JSON: {e}")
+            real = {json.dumps([f.inputs, f.output], sort_keys=True) for f in i.private_fixtures}
+            for n, f in enumerate(i.fixtures):
+                if json.dumps([f.inputs, f.output], sort_keys=True) in real:
+                    raise ContractError(
+                        f"public fixture {n} of {i.module}.{i.function} equals a private fixture; "
+                        "public fixtures must be decoys, not real behaviour")
+
+    # ---- views --------------------------------------------------------
+    def public_view(self) -> dict:
+        """Everything the frontier model is allowed to see. private_fixtures excluded."""
+        ifaces = []
+        for i in self.interfaces:
+            d = asdict(i)
+            d.pop("private_fixtures", None)
+            ifaces.append(d)
+        return {"public_brief": self.public_brief, "interfaces": ifaces}
+
+    def private_fixtures_dict(self) -> dict:
+        """{module: {function: [{inputs, output}]}} from the REAL examples."""
+        out: dict = {}
+        for i in self.interfaces:
+            out.setdefault(i.module, {})[i.function] = [
+                {"inputs": f.inputs, "output": f.output} for f in i.private_fixtures]
+        return out
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def public_text(self) -> str:
+        """Flattened outbound text, for the redaction gate."""
+        return json.dumps(self.public_view(), indent=2, sort_keys=True)

killchain/detector.py

@@ -0,0 +1,180 @@
+"""Model-based refusal-risk detector: Jev (TypeSafe) via the OpenRouter
+Decisions API.
+
+Jev is a structured decision model: it returns probabilities, not prose. For
+each span we ask one `noul` (yes/no) question per dimension in
+routing.DIMENSIONS, in a single request, and read all the answers back. A span
+that trips any dimension is pulled out of the public view and handed to the
+abliterated orchestrator to implement instead.
+
+Dimensions come from routing.py. Everything scored here is sent to OpenRouter
+and TypeSafe, so the harness only scores the CANDIDATE PUBLIC VIEW and, when
+`probe_raw_prompt` is on, spans of the raw prompt.
+
+`base_url = "fake"` selects a canned backend for pipeline tests.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.request
+import urllib.error
+from dataclasses import dataclass, field
+
+from killchain import routing
+
+
+class DetectorError(RuntimeError):
+    pass
+
+
+@dataclass
+class RiskVerdict:
+    label: str                          # where the span came from, e.g. "brief[2]"
+    text: str
+    scores: dict[str, float] = field(default_factory=dict)
+    flagged: bool = False
+
+    @property
+    def worst(self) -> tuple[str, float]:
+        return routing.worst_dimension(self.scores)
+
+
+def spans_from_public_view(pv: dict) -> list[tuple[str, str]]:
+    """Split the public view into independently scorable spans."""
+    out: list[tuple[str, str]] = []
+    paras = [p.strip() for p in re.split(r"\n\s*\n", pv["public_brief"]) if p.strip()]
+    for n, p in enumerate(paras):
+        out.append((f"brief[{n}]", p))
+    for i in pv["interfaces"]:
+        name = f"{i['module']}.{i['function']}"
+        out.append((f"iface {name} desc", i["description"]))
+        sig = ", ".join(f"{p['name']}: {p['type']} ({p.get('description', '')})" for p in i["params"])
+        out.append((f"iface {name} sig", f"{name}({sig}) -> {i['returns']}"))
+        for k, f in enumerate(i["fixtures"]):
+            out.append((f"iface {name} fixture[{k}]", json.dumps(f, sort_keys=True)))
+    return out
+
+
+def whole_view_text(pv: dict) -> str:
+    """The public view flattened, for the holistic pass.
+
+    Refusals are triggered by the shape of a task, not only by its sentences:
+    every span can be innocent while the assembled brief reads as 'clone this
+    product'. This text is scored once as the `overall` span.
+    """
+    parts = [pv["public_brief"]]
+    for i in pv["interfaces"]:
+        parts.append(f"{i['module']}.{i['function']}: {i['description']}")
+    return "\n".join(parts)
+
+
+def _questions(risky_terms: list[str]) -> dict:
+    terms = ", ".join(risky_terms) if risky_terms else "(none listed)"
+    safe = routing.SAFE.strip() + "\nKnown-risky terms and obvious variants of them: " + terms + "."
+    qs: dict = {}
+    for key, d in routing.DIMENSIONS.items():
+        qs[key] = {
+            "type": "noul",
+            "instructions": d["question"],
+            "criteria": {"true": d["risky"].strip() + "\nAlso true if: " + terms + ".",
+                         "false": safe},
+        }
+    qs["overall"] = {
+        "type": "noul",
+        "instructions": ("Taken as one task, is this the kind of build a frontier coding agent "
+                         "would hedge, ask about, simplify, or refuse?"),
+        "criteria": {
+            "true": ("Any of these, even once: brand or clone framing, reverse engineering, "
+                     "offensive security, harvesting, a regulated domain, another vendor's "
+                     "model, hedged claims, or scope big enough to negotiate away."),
+            "false": safe,
+        },
+    }
+    return qs
+
+
+def _call(cfg: dict, state: str, questions: dict) -> dict:
+    key = os.environ.get(cfg.get("api_key_env", "OPENROUTER_API_KEY"), "")
+    if not key:
+        raise DetectorError(f"env {cfg.get('api_key_env', 'OPENROUTER_API_KEY')} is not set")
+    body = {"model": cfg.get("model", "typesafe/jev-1.14"), "state": state, "questions": questions}
+    req = urllib.request.Request(
+        cfg.get("base_url", "https://openrouter.ai/api/alpha/decisions"),
+        data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {key}",
+                 "HTTP-Referer": "https://github.com/local/harness", "X-Title": "skoal-risk"})
+    try:
+        with urllib.request.urlopen(req, timeout=cfg.get("timeout", 60)) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        raise DetectorError(f"detector HTTP {e.code}: {e.read()[:500]!r}") from e
+    except urllib.error.URLError as e:
+        raise DetectorError(f"detector unreachable: {e}") from e
+
+
+def _read_scores(resp: dict) -> dict[str, float]:
+    answers = resp.get("answers") or {}
+    scores: dict[str, float] = {}
+    for dim in routing.DIMENSIONS:
+        try:
+            scores[dim] = float(answers[dim]["noul"])
+        except (KeyError, TypeError, ValueError):
+            continue
+    if not scores:
+        raise DetectorError(f"unexpected detector response: {json.dumps(resp)[:500]}")
+    return scores
+
+
+def _verdict(label: str, text: str, scores: dict[str, float]) -> RiskVerdict:
+    return RiskVerdict(label, text, scores, routing.classify(label, text, scores))
+
+
+def score_spans(cfg: dict, spans: list[tuple[str, str]],
+                risky_terms: list[str]) -> list[RiskVerdict]:
+    """Score each span against every dimension, then let routing.classify() rule."""
+    if cfg.get("base_url") == "fake":
+        from killchain.fakes import fake_detector
+        return [_verdict(l, t, s) for (l, t), s in zip(spans, fake_detector(spans))]
+    qs = _questions(risky_terms)
+    out: list[RiskVerdict] = []
+    for label, text in spans:
+        out.append(_verdict(label, text, _read_scores(_call(cfg, text, qs))))
+    return out
+
+
+def score_whole_view(cfg: dict, pv: dict, risky_terms: list[str]) -> RiskVerdict:
+    """The holistic pass over the assembled public view."""
+    text = whole_view_text(pv)
+    if cfg.get("base_url") == "fake":
+        from killchain.fakes import fake_overall
+        return _verdict("overall", text, fake_overall(text))
+    resp = _call(cfg, text, {"overall": _questions(risky_terms)["overall"]})
+    return _verdict("overall", text, _read_scores(resp))
+
+
+def describe(verdicts: list[RiskVerdict], only_flagged: bool = True) -> str:
+    rows = [v for v in verdicts if v.flagged] if only_flagged else verdicts
+    if not rows:
+        return "detector: no spans over threshold"
+    lines = [f"DETECTOR ROUTED {len(rows)} span(s) PRIVATE:"]
+    for v in rows:
+        dim, p = v.worst
+        lines.append(f"  {dim} p={p:.2f} {v.label}: {v.text[:160]!r}")
+    return "\n".join(lines)
+
+
+def risk_map(verdicts: list[RiskVerdict]) -> str:
+    """Human/LLM-readable table of span scores for the partition prompt."""
+    lines = []
+    for v in verdicts:
+        dim, p = v.worst
+        tag = f"PRIVATE {dim} p={p:.2f}" if v.flagged else f"public  {dim} p={p:.2f}"
+        lines.append(f"- [{tag}] {v.text}")
+    return "\n".join(lines) or "- (no spans)"
+
+
+def spans_from_prompt(prompt: str) -> list[tuple[str, str]]:
+    """Delegates to routing.split_prompt(). Only used when probe_raw_prompt is on."""
+    return routing.split_prompt(prompt)

killchain/doctor.py

@@ -0,0 +1,164 @@
+"""killchain doctor: tell a new user exactly what is missing.
+
+Every check reports ok / warn / fail and nothing here raises. The point is that
+a first run should never be a stack trace about a missing key three steps in.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+import killchain.localmodel as localmodel
+from killchain import paths
+
+OK, WARN, FAIL = "ok", "warn", "FAIL"
+
+
+@dataclass
+class Check:
+    name: str
+    state: str
+    detail: str
+    fix: str = ""
+
+
+def _key_state(cfg: dict, label: str) -> tuple[str, str, str]:
+    name = cfg.get("api_key_env", "")
+    if name and os.environ.get(name):
+        return f"${name} is set", "", f"{label} key found in the environment"
+    env_file = Path(cfg.get("env_file", "~/.hermes/.env")).expanduser()
+    if name and env_file.exists():
+        try:
+            found = any(line.startswith(name + "=") for line in env_file.read_text().splitlines())
+        except OSError:
+            found = False
+        if found:
+            return f"${name} found in {env_file}", "", f"{label} key read from {env_file}"
+    return "", f"set ${name}", f"{label} key not found"
+
+
+def run(cfg: dict) -> int:
+    checks: list[Check] = []
+
+    # --- config
+    try:
+        cp = paths.resolve_config(None)
+        checks.append(Check("config", OK, str(cp)))
+    except SystemExit as e:
+        checks.append(Check("config", FAIL, str(e), "run: killchain doctor --write-config"))
+
+    # --- frontier agent
+    backend = cfg.get("frontier", {}).get("backend", "claude")
+    exe = {"claude": "claude", "codex": "codex"}.get(backend)
+    if backend == "fake":
+        checks.append(Check("frontier", WARN, "backend=fake (canned replies)", "set backend in [frontier]"))
+    elif exe and shutil.which(exe):
+        checks.append(Check("frontier", OK, f"{exe} on PATH ({shutil.which(exe)})"))
+    else:
+        checks.append(Check("frontier", FAIL, f"{backend} backend but no `{exe}` on PATH",
+                            f"install {exe}, or use --frontier codex/claude/fake"))
+
+    # --- orchestrator key
+    och = cfg.get("orchestrator", {})
+    detail, fix, msg = _key_state(och, "orchestrator")
+    if och.get("base_url") == "fake":
+        checks.append(Check("orchestrator", WARN, "base_url=fake (canned replies)"))
+    else:
+        checks.append(Check("orchestrator", OK if detail else FAIL, detail or msg, fix))
+
+    # --- risk detector key
+    risk = cfg.get("risk", {})
+    if not risk.get("enabled", True):
+        checks.append(Check("risk scorer", WARN, "disabled (gate only)", "enable [risk] to score spans"))
+    elif risk.get("base_url") == "fake":
+        checks.append(Check("risk scorer", WARN, "base_url=fake (canned replies)"))
+    else:
+        detail, fix, msg = _key_state(risk, "OpenRouter")
+        checks.append(Check("risk scorer", OK if detail else FAIL, detail or msg, fix))
+
+    # --- private root: must exist, be writable, and NOT be world-readable
+    root = Path(cfg.get("paths", {}).get("private_root", str(paths.private_root()))).expanduser()
+    try:
+        root.mkdir(parents=True, exist_ok=True)
+        probe = root / ".write-test"
+        probe.write_text("ok")
+        probe.unlink()
+        mode = root.stat().st_mode
+        if mode & 0o077:
+            # Holds the raw prompt and real fixtures; fix it rather than nag.
+            paths.secure_mkdir(root)
+            mode = root.stat().st_mode
+            if mode & 0o077:
+                checks.append(Check("private root", WARN, f"{root} still group/world-accessible",
+                                    f"chmod 700 {root}"))
+            else:
+                checks.append(Check("private root", OK, f"{root} (tightened to 0700)"))
+        else:
+            checks.append(Check("private root", OK, f"{root} (mode {oct(mode & 0o777)})"))
+    except OSError as e:
+        checks.append(Check("private root", FAIL, f"{root}: {e}", "pass --private-root to a writable dir"))
+
+    # --- workspace
+    ws = Path(cfg.get("paths", {}).get("workspace", "")).expanduser()
+    try:
+        ws.mkdir(parents=True, exist_ok=True)
+        checks.append(Check("workspace", OK, str(ws)))
+    except OSError as e:
+        checks.append(Check("workspace", FAIL, f"{ws}: {e}", "pass --workspace"))
+
+    # --- denylist
+    dl = paths.denylist_path(cfg)
+    try:
+        import killchain.gate as gate
+        rules = gate.load_denylist(dl)
+        if rules:
+            checks.append(Check("denylist", OK, f"{len(rules)} rule(s) in {dl}"))
+        else:
+            checks.append(Check("denylist", WARN, f"empty ({dl}) — gate will only catch builtin secrets",
+                                "add product names, codenames and licence names"))
+    except SystemExit as e:
+        checks.append(Check("denylist", FAIL, str(e), f"fix or delete {dl}"))
+
+    # --- the one check that proves the network path works
+    if risk.get("enabled", True) and risk.get("base_url") != "fake" and _key_state(risk, "OpenRouter")[0]:
+        import killchain.detector as detector
+        try:
+            spans = detector.spans_from_prompt("a small test span about sorting a list")
+            got = detector.score_spans(risk, spans[:1], [])
+            score = got[0].scores.get("overall", got[0].scores)
+            checks.append(Check("risk round-trip", OK, f"scored 1 span: {score}"))
+        except Exception as e:  # noqa: BLE001 - doctor must never raise
+            checks.append(Check("risk round-trip", FAIL, f"{type(e).__name__}: {e}",
+                                "check OPENROUTER_API_KEY and network"))
+
+    # --- orchestrator round-trip (cheap, skipped when the base_url is fake)
+    if och.get("base_url") != "fake" and _key_state(och, "orchestrator")[0]:
+        try:
+            localmodel.chat({**och, "timeout": 30}, [{"role": "user", "content": "reply with: ok"}],
+                            max_tokens=8)
+            checks.append(Check("orchestrator round-trip", OK, "chat endpoint answered"))
+        except Exception as e:  # noqa: BLE001
+            checks.append(Check("orchestrator round-trip", FAIL, f"{type(e).__name__}: {e}",
+                                "check the key, base_url and model name"))
+
+    # --- report
+    width = max(len(c.name) for c in checks)
+    icon = {OK: "ok  ", WARN: "warn", FAIL: "FAIL"}
+    failed = 0
+    for c in checks:
+        print(f"  {icon[c.state]}  {c.name.ljust(width)}  {c.detail}")
+        if c.fix:
+            print(f"          {''.ljust(width)}  -> {c.fix}")
+        failed += c.state == FAIL
+    fatal = [c for c in checks if c.state == FAIL and c.name in ("config", "frontier", "orchestrator")]
+    print()
+    if failed:
+        print(f"{failed} check(s) failed.")
+    else:
+        print("all checks passed — try: killchain \"your task\"")
+    if failed:
+        print("Still stuck? War stories and how this works: "
+              "https://youtube.com/@drjoshcsimmons")
+    return 1 if fatal else 0