@profoundry-us/highball 0.4.1 → 0.6.0

package/ONBOARDING.md

@@ -3,10 +3,10 @@
 You are setting up Highball in this repository. Highball gives you (the
 agent) guardrails while you work — a checks runner your Claude Code hooks
 fire on every edit and turn end, whose exit code 2 blocks you until the
-repo's rules pass — and gives your human a hosted dashboard recording
-every run. You are configuring the tool that will check your own future
-work: set it up so the rules reflect what this repo already trusts, not
-what you wish it did.
+repo's rules pass. Runs can optionally be reported to your human's own
+PostHog project. You are configuring the tool that will check your own
+future work: set it up so the rules reflect what this repo already trusts,
+not what you wish it did.
 
 Work through the steps in order. Steps marked **human** need your human's
 input or action — ask, don't guess, and never handle credential values
@@ -100,8 +100,11 @@ like this:
 version: 1
 project: my-mud            # ask your human if their org has slug conventions
 
-reporting:
-  url: https://highball.example.com   # human provides; committed, not secret
+# Optional — see step 4. Skip unless your human asks for telemetry.
+# reporting:
+#   posthog:
+#     host: https://us.i.posthog.com   # human provides; committed, not secret
+#     project_key: phc_xxx
 
 # Toolchain in Docker: declare the wrapper once. -T is mandatory (hook
 # shells have no TTY); --workdir should be the container's repo mount.
@@ -143,17 +146,25 @@ Decision rules:
   repo-relative) to every rule — scripts that want changed-only behavior
   can read it instead of shelling out to git.
 
-## 4. Credentials — **human**
+## 4. Telemetry — **human**, and optional
 
-You must never see, type, or store a token value. Ask your human to:
+Highball enforces with no account and no network. Reporting is a separate,
+optional decision, and it is your human's to make — ask, do not assume.
 
-1. Create this project (and a token for it) in their Highball app.
-2. Run `npx @profoundry-us/highball login` themselves — interactively, or piping the
-   token via `--token-stdin` to keep it out of shell history.
+If they want it, there are two ways, and the choice is theirs:
 
-This stores the token in `~/.highball/credentials.json` (machine-local,
-0600, keyed host → project). CI uses `HIGHBALL_URL`/`HIGHBALL_TOKEN` env
-vars instead. The repo tree never contains a secret.
+- **Committed:** a `reporting.posthog` block in `checks.yml` with their
+  PostHog host and project key. That key is write-only by design (it is the
+  same one that ships in client-side web bundles), so it is committed
+  config, not a secret — there is no login step and no credentials file.
+- **Per machine:** `HIGHBALL_POSTHOG_KEY` in the environment, with no block
+  in `checks.yml` at all. The `env` block of `~/.claude/settings.json`
+  reaches every repo's hooks. Your human sets this themselves; never ask
+  for the key value or write it anywhere.
+
+If they would rather not send anything anywhere, skip both: the local
+journal (`highball runs`) already records every run in more detail than
+PostHog receives.
 
 ## 5. Verify — all four proofs, not just the happy path
 
@@ -165,17 +176,19 @@ vars instead. The repo tree never contains a secret.
    failing file (e.g. a syntax error in a `tmp_highball_plant.*` file),
    run the fast path, confirm `FAILED` plus exit code 2 plus the failure
    text on stderr — then delete the plant and confirm green again.
-4. **The witness:** every run above should print
-   `reported to <host> (run <id>)`. If you see
-   `highball reporting skipped: …` instead, diagnose in order: is
-   `reporting.url` set? did the human run `login` for this exact URL and
-   project slug? is the Highball app reachable from this machine?
+4. **The record:** `npx @profoundry-us/highball runs` lists the runs you
+   just made, with per-rule status. If your human opted into telemetry,
+   each run also prints `reported N events to <host>`; if you see
+   `highball posthog reporting skipped: …` instead, check the host and
+   project key in `reporting.posthog` and whether this machine can reach
+   the host. Reporting never blocks a run, so this is the last thing to
+   fix, not the first.
 
 ## 6. Report back — **human**
 
 Tell your human, concretely: which rules you wired and why each is
 fast/turn-end/todo; what you deliberately did NOT gate (slow suites,
 live-server tests); that hooks now block your turns on failures and how
-to remove them (`.claude/settings.json`) if they ever need to; and where
-credentials live. Follow this repo's own norms about committing the new
-files — do not commit without being asked.
+to remove them (`.claude/settings.json`) if they ever need to; and whether
+you wired telemetry or left it off. Follow this repo's own norms about
+committing the new files — do not commit without being asked.

package/README.md

@@ -1,13 +1,16 @@
 # @profoundry-us/highball
 
-The Highball runner: executes a repo's `.highball/checks.yml` rules, blocks AI
-coding agents on failure (exit 2, the Claude Code hook contract), and reports
-every run to a Highball dashboard — think "local CI for AI agents": the checks
-run and enforce on your machine while the dashboard records what happened.
-Enforcement stays local; Highball is the witness and system of record — the
-runner never uploads code, only pass/fail plus log tails. Reporting is always
-best-effort: no token or no reachable dashboard means checks still run and
-block, they just aren't recorded.
+The Highball runner: executes a repo's `.highball/checks.yml` rules and blocks
+AI coding agents on failure (exit 2, the Claude Code hook contract) — "local
+CI for AI agents". Enforcement is entirely local and needs no account, no
+network, and no configuration beyond `checks.yml`.
+
+Runs can optionally be reported to PostHog for team-wide visibility. That is
+the witness half, and it is deliberately somebody else's server: you point at
+your own PostHog project, so Highball never takes custody of your data. The
+runner never uploads code — only rule ids, pass/fail, durations, and a
+one-line summary of a failure. Reporting is always best-effort: an unreachable
+endpoint means checks still run and still block, they just aren't recorded.
 
 ## Install
 
@@ -22,7 +25,7 @@ From a local tarball (pre-release):
 
 ```bash
 npm pack                                   # in this repo → profoundry-us-highball-<v>.tgz
-npm install --save-dev ../highball-runner/profoundry-us-highball-<v>.tgz
+npm install --save-dev ../highball/profoundry-us-highball-<v>.tgz
 ```
 
 ## Setup: let the repo's own agent do it
@@ -34,30 +37,41 @@ installing the package, tell the repo's Claude Code agent:
 
 [ONBOARDING.md](ONBOARDING.md) (which that command prints) walks the agent
 through surveying the repo's real toolchain, scaffolding, writing rules that
-reflect what the repo already trusts, handing the credentials step to the
-human, and verifying all four proofs — including that exit 2 actually blocks.
+reflect what the repo already trusts, and verifying all four proofs —
+including that exit 2 actually blocks.
 
 The pieces, for reference or manual setup:
 
 ```bash
 npx @profoundry-us/highball init    # scaffolds checks.yml + Claude Code hooks
-npx @profoundry-us/highball login   # stores a project token (once per machine)
 ```
 
 `init` never overwrites an existing `checks.yml` and never edits an existing
-`.claude/settings.json` (it prints the hook snippet to merge by hand).
-`login` writes `~/.highball/credentials.json` (host → project → token, 0600);
-pipe the token via `--token-stdin` to keep it out of shell history. CI uses
-`HIGHBALL_URL` / `HIGHBALL_TOKEN` env vars instead.
+`.claude/settings.json` (it prints the hook snippet to merge by hand). There
+is no login step: the only credential Highball takes is a PostHog project
+key, which is write-only by design and lives in committed config.
+
+The fast hook matches `Write|Edit|Bash` and runs `--fast --if-changed`.
+Agents in auto mode edit through Bash — `sed`, heredocs, scripts — so a hook
+on the edit tools alone never fires for them (one repo here went two weeks
+with zero fast runs that way while full runs kept landing). Matching Bash
+too would run the fast rules after every command, most of them reads, so
+`--if-changed` fingerprints the working tree (HEAD plus each dirty path's
+size and mtime) and exits at once when nothing moved since the last run.
+Older installs: change the matcher and add the flag by hand.
 
 ## checks.yml
 
 ```yaml
 version: 1
 project: my-app
+# runs_limit: 25   # rows the MCP widget / list_runs return; HIGHBALL_RUNS_LIMIT overrides
 
+# Optional. Omit the block entirely to keep runs in the local journal only.
 reporting:
-  url: https://highball.example.com   # per-team, not a secret — committed
+  posthog:
+    host: https://us.i.posthog.com    # EU cloud or self-hosted also fine
+    project_key: phc_xxx              # write-only by design — committed
 
 # Containerized toolchain? Declare the wrapper once and every rule runs
 # through it; rules opt out with `exec: host`. Rule definitions stay
@@ -89,6 +103,72 @@ The runner computes the branch's changed-file list once (it owns git) and
 hands it to every rule via `HIGHBALL_CHANGED_FILES` — check scripts stay pure
 analyzers and need no git in their execution context.
 
+## Turning it off
+
+Three switches, differing in who they affect and — the part that usually
+decides it — when they take effect:
+
+```bash
+touch .highball/disabled       # this checkout, gitignored, next run
+```
+
+```yaml
+enabled: false                 # in checks.yml — committed, everyone, next run
+```
+
+```bash
+export HIGHBALL_DISABLED=1     # your whole machine, next session restart
+```
+
+Any of them makes `highball run` exit 0 immediately, with no rule executed, no
+journal entry, and nothing reported. Hooks and rules stay exactly where they
+are, so switching back on is a one-line revert.
+
+| | takes effect | scope | committed |
+| --- | --- | --- | --- |
+| `.highball/disabled` | next run | this checkout | no — `init` gitignores it |
+| `enabled: false` | next run | one repo, everyone who clones it | yes |
+| `HIGHBALL_DISABLED` | next Claude Code restart, for hooks | every repo, your machine | no |
+
+**Reach for the marker file first.** `touch .highball/disabled` while an agent
+session is running and the very next hook run skips; delete it and the run
+after that is armed again. Both directions are live because the file is
+checked on every run and every hook invocation is a new process — there is no
+state anywhere and nothing to restart. `init` writes a `.highball/.gitignore`
+alongside it, so a switch-off in your checkout can't ride along in a commit.
+
+Anything you write into the marker comes back as the reason on every run,
+which is what the person who finds the checks off next week actually needs:
+
+```console
+$ echo "bisecting a flaky spec" > .highball/disabled
+$ npx @profoundry-us/highball run --fast
+highball: disabled by .highball/disabled (bisecting a flaky spec) — no checks run
+```
+
+`enabled: false` is the committed counterpart, for a repo genuinely stepping
+away from its checks. It lands in a diff, which is what you want when the
+decision belongs to the team rather than to your afternoon.
+
+`HIGHBALL_DISABLED` is an ordinary environment variable, so a hook sees
+whatever value the Claude Code process had when it started — Claude Code
+writes settings `env` entries into its environment at launch, and a shell
+`export` after that never reaches an already-running session. That makes it
+the right switch for a machine-wide default you rarely change, and the wrong
+one for a mid-session toggle. Like the marker, it is read *before*
+`checks.yml`, so both still work when the config is itself what's broken.
+
+`HIGHBALL_DISABLED=0`, `false`, `no`, `off` and empty all mean **not**
+disabled. Anything else disables. Plain truthiness would make `=0` stop every
+check in the repo, which is exactly the "is the guardrail live right now?"
+doubt this switch exists to remove.
+
+None of the three is silent. Each prints a line on every run, because a guardrail
+that has quietly stopped guarding is worse than no guardrail — the next
+person reads green and believes it. For the same reason `enabled:` accepts
+only a real boolean: `enabled: "false"` and `enabled: no` are strings, and
+rather than leaving checks quietly on, they fail loudly.
+
 ## AI-judged rules
 
 A rule with `rubric:` instead of `run:` is judged by headless Claude rather
@@ -121,6 +201,66 @@ Three properties are enforced by the runner rather than left to each repo:
 Rubrics live with the opinions they express: a framework pack such as
 `@profoundry-us/highball-rails` ships them, and the runner supplies the engine.
 
+## Reporting to PostHog (optional)
+
+`reporting.posthog` sends runs to PostHog — the runner's only telemetry path.
+A team that already runs PostHog needs no server for this, and a team that
+doesn't can skip the block entirely and use the local journal. The project key
+is write-only by design — it is the same key PostHog has you ship in browser
+bundles, and all it can do is capture events — so committing it is safe:
+no login step, no credentials file.
+
+If you would still rather keep it out of the repo, set the environment
+instead. `HIGHBALL_POSTHOG_KEY` (or `POSTHOG_API_KEY`) on its own turns
+reporting on with no `reporting:` block at all, and `HIGHBALL_POSTHOG_HOST`
+(or `POSTHOG_HOST`) points it at an EU or self-hosted instance; either wins
+over committed config, which is also how CI redirects a run. One place that
+reaches every repo's hooks is the `env` block of your user-level Claude Code
+settings, `~/.claude/settings.json`:
+
+```json
+{ "env": { "HIGHBALL_POSTHOG_KEY": "phc_your_key" } }
+```
+
+The trade-off is that reporting is then per machine rather than per repo: a
+teammate cloning the repo reports nothing until they set the key too.
+
+The whole run leaves in ONE request to `/batch/`. PostHog events are
+immutable, which suits a runner that already defers reporting to after the
+checks finish.
+
+Two event types per run:
+
+| event | one per | key properties |
+| --- | --- | --- |
+| `highball_run` | run | `status`, `duration_ms`, `rules_passed/failed/todo`, `rules_run[]`, `failed_rules[]` |
+| `highball_check` | rule result | `rule_id`, `rule_name`, `status`, `duration_ms`, `summary`, `command` |
+
+Run context (`project`, `branch`, `commit`, `trigger`, `session_key`,
+`runner_version`) is repeated on every event rather than joined at query time,
+because PostHog has no join back to a run: a breakdown like "failure rate by
+rule, on this branch only" needs `branch` on the check event itself.
+`rules_run[]` is the denominator for any per-rule rate that spans runs whose
+rulesets differ.
+
+Log tails are never sent — multi-kilobyte blobs in event properties bloat the
+column store and slow every query that touches it. Failures carry a one-line
+`summary`; the full output stays in the local journal (below).
+
+Volume is smaller than "runs on every edit" suggests, because agent edits
+batch into turns. Measured across 842 real runs on one developer's machine
+over 18 active days and 9 projects: a median of 22 runs/day, `edit` and `stop`
+runs at close to 1.3:1, and ~15k events/month/dev at the model above.
+
+Dashboard queries live in [docs/posthog-queries.sql](docs/posthog-queries.sql)
+— rule cost vs. benefit, failure rate by week, fast-path latency, repo health,
+and todo debt. They are versioned rather than left as PostHog UI state, which
+drifts and cannot be reviewed.
+
+Events are attributed to `git config user.email`, falling back to
+`user@hostname` when git has no identity (CI images, fresh containers).
+`HIGHBALL_POSTHOG_DISTINCT_ID` overrides it.
+
 ## The MCP dashboard widget
 
 `highball mcp` serves the journal over MCP (stdio) with three tools —
@@ -142,6 +282,18 @@ The journal it reads is machine-global (`~/.highball/runs/`), so one
 registration covers every repo on that machine — there is no per-repo MCP
 setup.
 
+Which project the widget shows is never guessed. Hosts spawn the server with
+no useful working directory (Claude Desktop and Claude Code both use `/`), so
+`list_runs` resolves the project from its `project` or `dir` argument, a
+`.highball/checks.yml` at the server's cwd, or the client's MCP roots. When
+none of those names a repo it returns the journaled projects for the widget
+to offer as a picker, rather than showing whichever repo happened to run most
+recently. An agent calling from inside a repo should pass `dir`.
+
+`list_runs` returns the newest 25 runs, and the widget says so at the top.
+Change it per call with `limit`, per machine with `HIGHBALL_RUNS_LIMIT`, or
+per repo with `runs_limit:` in checks.yml.
+
 The split is capability-driven, not guesswork: the server reads the
 client's initialize capabilities (`io.modelcontextprotocol/ui`) — hosts
 that render MCP Apps get a short text summary plus the widget; everything
@@ -151,17 +303,18 @@ plays the host role against the real `assets/dashboard.html` and live
 journal data, so widget edits are a reload away instead of a Claude
 Desktop restart.
 
-## Run history without a dashboard
+## Run history, with no telemetry at all
 
-Every run also appends to a local journal (`~/.highball/runs/<project>.jsonl`,
+Every run appends to a local journal (`~/.highball/runs/<project>.jsonl`,
 pruned to the last 200) — unconditionally, whether or not reporting is
 configured. `npx @profoundry-us/highball runs` lists recent runs; adding a
 number shows one run's detail with failure output, and `--logs` prints every
-rule's captured output, GitHub-Actions-style — the journal keeps the last
-10KB per rule, pass or fail, while the dashboard receives failure tails
-only. So the runner is self-sufficient out of the box: the hosted
-dashboard adds team visibility, history beyond your machine, and
-attribution — it's never required to see what happened.
+rule's captured output, GitHub-Actions-style.
+
+The journal is the richer of the two records: it keeps the last 10KB per rule
+pass or fail, while PostHog gets a one-line summary and no logs at all. So the
+runner is fully self-sufficient with no `reporting:` block — PostHog adds
+cross-developer trends, not visibility you'd otherwise lack.
 
 ## Roadmap
 

package/assets/dashboard.html

@@ -194,6 +194,7 @@
     }
     app.innerHTML =
       header("Highball — pick a project", "") +
+      `<div class="group">no .highball/checks.yml in the current repo, so nothing is shown by default</div>` +
       `<div class="empty" style="padding:10px 6px">` +
       projects.map((slug) => `<button data-project="${esc(slug)}" style="margin:0 4px">${esc(slug)}</button>`).join("") +
       `</div>`;
@@ -225,8 +226,14 @@
         <span class="meta">${esc(tally(run.results))}</span>
       </div>`;
     }).join("");
+    // Say up front when the list is cut short — the host's own history
+    // may be much longer than what the widget shows.
+    const scope = sc.total > sc.runs.length
+      ? `<div class="group" style="font-style:normal">showing the last ${sc.runs.length} of ${sc.total} runs` +
+        ` &middot; raise with <span class="mono">runs_limit</span> in checks.yml or <span class="mono">HIGHBALL_RUNS_LIMIT</span></div>`
+      : "";
     app.innerHTML =
-      header(`Highball · ${esc(sc.project)}`, rerunButtons()) +
+      header(`Highball · ${esc(sc.project)}`, rerunButtons()) + scope +
       (rows || `<div class="empty">No runs recorded yet.</div>`);
     app.querySelectorAll(".row").forEach((el) =>
       el.addEventListener("click", () =>

package/bin/highball.js

@@ -5,7 +5,6 @@
 // the failure output back".
 import { run } from "../lib/run.js";
 import { init } from "../lib/init.js";
-import { login } from "../lib/login.js";
 import { onboard } from "../lib/onboard.js";
 import { runs } from "../lib/runs.js";
 import { mcp } from "../lib/mcp.js";
@@ -18,18 +17,22 @@ Usage:
   highball run [--fast]     Run this repo's .highball/checks.yml rules.
                             Exits 2 on failure (blocks Claude Code hooks).
                             --fast runs only rules marked fast: true.
+                            --if-changed skips when the working tree is
+                            unchanged since the last run (for hooks that
+                            also match Bash).
+                            Switched off by .highball/disabled (this
+                            checkout, gitignored), \`enabled: false\` in
+                            checks.yml (committed, whole team), or
+                            HIGHBALL_DISABLED=1 (your machine).
   highball init             Scaffold .highball/checks.yml and Claude Code
                             hooks in the current repo.
-  highball login            Store a project token in
-                            ~/.highball/credentials.json. Reads the token
-                            from stdin with --token-stdin (recommended).
   highball onboard          Print the setup guide written for this repo's
                             AI agent — tell your agent to run this and
                             follow it.
   highball runs [n]         Local run history (newest first) from
-                            ~/.highball/runs — no dashboard needed.
-                            With a number, that run's detail; add
-                            --logs for every rule's captured output.
+                            ~/.highball/runs. With a number, that run's
+                            detail; add --logs for every rule's captured
+                            output.
   highball mcp              Serve run history over MCP (stdio), with an
                             MCP Apps dashboard widget for hosts that
                             render them (e.g. Claude Desktop).
@@ -42,9 +45,6 @@ switch (command) {
   case "init":
     process.exit(await init(args));
     break;
-  case "login":
-    process.exit(await login(args));
-    break;
   case "onboard":
     process.exit(await onboard(args));
     break;

package/lib/config.js

@@ -1,12 +1,10 @@
 // Config resolution, kept pure where possible so tests can exercise the
 // decision logic without a filesystem.
 import { readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import YAML from "yaml";
 
 export const CONFIG_PATH = ".highball/checks.yml";
-export const CREDENTIALS_PATH = join(homedir(), ".highball", "credentials.json");
 
 // Loads .highball/checks.yml from the given repo root. Throws with a
 // friendly message — `highball run` outside a configured repo should read
@@ -18,6 +16,17 @@ export function loadConfig(root = process.cwd()) {
   }
   const config = YAML.parse(readFileSync(path, "utf8"));
   if (!config?.project) throw new Error(`${CONFIG_PATH} is missing \`project:\`.`);
+  // A kill switch that silently fails to kill is the worst of both worlds,
+  // so only a real boolean counts and anything else is an error rather than
+  // a shrug. `enabled: no` parses as the string "no" under YAML 1.2 and
+  // `enabled: "false"` as a string; both are truthy, so a typo would leave
+  // the repo running checks its author believed were off.
+  if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+    throw new Error(
+      `${CONFIG_PATH}: \`enabled:\` must be true or false, not ` +
+        `\`${config.enabled}\` (${typeof config.enabled}).`
+    );
+  }
   if (!Array.isArray(config.checks)) {
     throw new Error(`${CONFIG_PATH} is missing its \`checks:\` list.`);
   }
@@ -29,23 +38,81 @@ export function loadConfig(root = process.cwd()) {
       );
     }
   }
+  // The dashboard sink is gone; PostHog is the only telemetry path. A repo
+  // carrying the old block would otherwise report nowhere and say nothing
+  // about it — the same silent-pass shape that makes stale config dangerous.
+  if (config.reporting?.url) {
+    console.error(
+      `highball: ${CONFIG_PATH} has \`reporting.url\`, which is no longer ` +
+        "supported. Runs report to PostHog via `reporting.posthog`, or " +
+        "nowhere at all. Delete the key to silence this."
+    );
+  }
+
   return config;
 }
 
-// The reporting URL is per-team committed config; the token never lives
-// in the repo tree: env var (CI) wins, else the machine-local credentials
-// file keyed host → project (the .npmrc / gh-hosts pattern, written by
-// `highball login`).
-export function resolveReporting(config, env = process.env, credentials = readCredentials()) {
-  const url = env.HIGHBALL_URL || config.reporting?.url || null;
-  const token =
-    env.HIGHBALL_TOKEN || (url && credentials?.[url]?.[config.project]) || null;
-  return { url, token };
+// The per-machine off switch, read fresh on every `highball run` — there is
+// no state anywhere, so unsetting the variable re-arms the checks with
+// nothing to clean up.
+//
+// Falsey spellings mean "don't disable" rather than "disable". Plain
+// truthiness would make `HIGHBALL_DISABLED=0` stop every check in the repo,
+// which is precisely the doubt about whether the guardrail is live that this
+// switch exists to remove. Anything else — 1, true, yes, on, or a bare
+// value — disables.
+const NOT_DISABLED = new Set([ "", "0", "false", "no", "off" ]);
+
+export function disabledByEnv(env = process.env) {
+  const value = env.HIGHBALL_DISABLED;
+  if (value === undefined) return false;
+  return !NOT_DISABLED.has(String(value).trim().toLowerCase());
+}
+
+// The per-checkout off switch: an untracked marker file beside checks.yml.
+//
+// It exists because the other two each miss the common case. `enabled: false`
+// is committed, so switching your own checkout off can ship to everyone;
+// HIGHBALL_DISABLED is an environment variable, so a hook only sees a change
+// after the agent session restarts. This one is per repo, per checkout, and
+// re-read on every run like checks.yml — `touch` and `rm`, effective on the
+// next run, and `.highball/.gitignore` keeps it out of commits.
+export const DISABLED_MARKER = ".highball/disabled";
+
+// Presence is the whole signal; any text inside is the reason, echoed back on
+// every run so "why are the checks off in here?" has an answer that outlives
+// whoever switched them off.
+export function disabledByMarker(root = process.cwd()) {
+  const path = join(root, DISABLED_MARKER);
+  if (!existsSync(path)) return null;
+  try {
+    return { reason: readFileSync(path, "utf8").split("\n")[0].trim() };
+  } catch {
+    // An unreadable marker still counts: it was put there on purpose, and
+    // guessing "probably fine, run the checks" is the wrong way to be wrong.
+    return { reason: "" };
+  }
 }
 
-export function readCredentials(path = CREDENTIALS_PATH) {
-  if (!existsSync(path)) return {};
-  return JSON.parse(readFileSync(path, "utf8"));
+// PostHog is the runner's telemetry sink. There is no secret to resolve: a
+// PostHog project key is write-only by design, so it lives in committed
+// config right next to the host — no login step, no credentials file. Env
+// vars still win so CI can point a run somewhere else without editing the
+// repo.
+//
+// The host defaults to PostHog's US cloud; EU and self-hosted installs set
+// it explicitly.
+const POSTHOG_DEFAULT_HOST = "https://us.i.posthog.com";
+
+export function resolvePosthog(config, env = process.env) {
+  const posthog = config.reporting?.posthog;
+  const key =
+    env.HIGHBALL_POSTHOG_KEY || env.POSTHOG_API_KEY || posthog?.project_key || null;
+  if (!key) return { host: null, key: null };
+
+  const host =
+    env.HIGHBALL_POSTHOG_HOST || env.POSTHOG_HOST || posthog?.host || POSTHOG_DEFAULT_HOST;
+  return { host, key };
 }
 
 // The execution-context decision (ADR 202608): rule definitions stay

package/lib/git.js

@@ -0,0 +1,12 @@
+// Git facts about the current checkout, for stamping onto reported runs.
+// Never throws: a run outside a repo, or with no commits yet, reports empty
+// strings rather than failing the checks.
+import { execSync } from "node:child_process";
+
+export function git(command) {
+  try {
+    return execSync(`${command} 2>/dev/null`, { encoding: "utf8" }).trim();
+  } catch {
+    return "";
+  }
+}