@profoundry-us/highball 0.4.0 → 0.5.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,18 @@ 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.
-
-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.
+If they want it, they add a `reporting.posthog` block to `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. If
+they would rather not send anything anywhere, skip the block: 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 +169,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
@@ -121,6 +135,51 @@ 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, so it is committed config: no login step, no
+credentials file. `HIGHBALL_POSTHOG_KEY` / `HIGHBALL_POSTHOG_HOST` (or
+`POSTHOG_API_KEY` / `POSTHOG_HOST`) override it for CI.
+
+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 +201,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 +222,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,18 @@ 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.
-  highball init             Scaffold .highball/checks.yml and Claude Code
+                            --if-changed skips when the working tree is
+                            unchanged since the last run (for hooks that
+                            also match Bash).
+  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 +41,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
@@ -29,23 +27,39 @@ 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 };
-}
+// 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 };
 
-export function readCredentials(path = CREDENTIALS_PATH) {
-  if (!existsSync(path)) return {};
-  return JSON.parse(readFileSync(path, "utf8"));
+  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 "";
+  }
+}

package/lib/init.js

@@ -13,11 +13,12 @@ const CHECKS_TEMPLATE = (project) => `# ${project}'s Highball rules — the file
 version: 1
 project: ${project}
 
-# Where runs get reported. The URL is per-team and not a secret, so it
-# lives here in committed config; the token never enters the repo — run
-# \`highball login\` once per machine (or set HIGHBALL_TOKEN in CI).
+# Optional telemetry. The PostHog project key is write-only by design, so
+# it is committed config — there is no login step and no credentials file.
 # reporting:
-#   url: https://your-highball-host
+#   posthog:
+#     host: https://us.i.posthog.com
+#     project_key: phc_your_key
 
 # If this repo's toolchain lives in a container, declare the wrapper once
 # and every rule runs through it; rules that belong on the host opt out
@@ -39,12 +40,19 @@ checks:
 // Always the SCOPED command. The unscoped npm name belongs to an unrelated
 // package, so a bare `npx highball` in a committed hook is one uninstalled
 // checkout away from fetching a stranger's code and running it on every edit.
+//
+// The fast hook matches Bash as well as the edit tools: agents in auto mode
+// edit through Bash, and a hook on Write|Edit alone never fires for them.
+// --if-changed keeps the Bash firings free when the tree hasn't moved.
 const HOOKS_JSON = {
   hooks: {
     PostToolUse: [
       {
-        matcher: "Write|Edit",
-        hooks: [{ type: "command", command: "npx @profoundry-us/highball run --fast" }]
+        matcher: "Write|Edit|Bash",
+        hooks: [{
+          type: "command",
+          command: "npx @profoundry-us/highball run --fast --if-changed"
+        }]
       }
     ],
     Stop: [
@@ -82,8 +90,8 @@ export async function init() {
   }
 
   console.log(
-    "\nnext: fill in .highball/checks.yml, uncomment reporting.url, and run" +
-      "\n  highball login   # stores this machine's project token"
+    "\nnext: fill in .highball/checks.yml, and optionally uncomment the" +
+      "\nreporting.posthog block to send runs to PostHog."
   );
   return 0;
 }

package/lib/mcp.js

@@ -21,34 +21,61 @@ const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8")
 ).version;
 
-// The server may be launched from a repo (project inferable) or from a
-// host like Claude Desktop whose cwd is nowhere useful. Resolution order:
-// explicit argument, the cwd's checks.yml, then the journal with the
-// newest run — the repo being actively worked in IS the current project.
-// Journal records carry the repo dir (since runs record process.cwd()),
-// so every path out of here can ground the widget's re-run buttons.
-function resolveProject(explicit) {
-  if (explicit) return { project: explicit, dir: latestDirFor(explicit) };
+// The host decides the server's working directory, and real hosts give it
+// nothing useful — Claude Desktop and Claude Code both spawn it at `/`. So
+// "the current repo" has to arrive some other way: an explicit `project`
+// or `dir` argument, a checks.yml at cwd, or the client's MCP roots.
+// Nothing else is guessed. In particular the journal is NOT a fallback:
+// "whichever project ran most recently on this machine" is usually some
+// other repo, and a widget that silently shows another project's runs
+// reads as this project's. Unresolved means the widget offers a picker.
+//
+// Journal records carry the repo dir (runs record process.cwd()), so an
+// explicit project still grounds the widget's re-run buttons. The loaded
+// config rides along so per-repo settings (runs_limit) can apply.
+export function resolveProject({
+  project, dir, cwd = process.cwd(), roots = [], journalDir
+} = {}) {
+  if (project) {
+    const home = dir ?? latestDirFor(project, journalDir);
+    return { project, dir: home, config: tryLoad(home) };
+  }
+  for (const candidate of [ dir, cwd, ...roots ].filter(Boolean)) {
+    const config = tryLoad(candidate);
+    if (config) return { project: config.project, dir: candidate, config };
+  }
+  return { project: null, dir: null, config: null };
+}
+
+function tryLoad(root) {
+  if (!root) return null;
   try {
-    return { project: loadConfig().project, dir: process.cwd() };
+    return loadConfig(root);
   } catch {
-    let current = null;
-    for (const project of journaledProjects()) {
-      const newest = readRuns(project)[0];
-      if (!newest) continue;
-      if (!current || newest.started_at > current.started_at) {
-        current = { project, started_at: newest.started_at };
-      }
-    }
-    if (!current) return { project: null, dir: null };
-    return { project: current.project, dir: latestDirFor(current.project) };
+    return null;
   }
 }
 
 // Newest journal record that knows its repo dir (older records predate
 // the field).
-function latestDirFor(project) {
-  return readRuns(project).find((run) => run.dir)?.dir ?? null;
+function latestDirFor(project, journalDir) {
+  return readRuns(project, journalDir).find((run) => run.dir)?.dir ?? null;
+}
+
+// How many runs list_runs returns. 200 journaled runs is a fine history and
+// a terrible tool result — the structured payload alone reaches ~300KB,
+// which text-only hosts hand straight to the model. Resolution: the call's
+// `limit`, then HIGHBALL_RUNS_LIMIT, then `runs_limit:` in checks.yml (only
+// present when the project resolved through a repo), then the default.
+export const DEFAULT_RUNS_LIMIT = 25;
+
+export function resolveRunsLimit({ limit, env = process.env, config } = {}) {
+  for (const candidate of [ limit, env.HIGHBALL_RUNS_LIMIT, config?.runs_limit ]) {
+    if (candidate == null || candidate === "") continue;
+    const n = Number(candidate);
+    if (Number.isInteger(n) && n > 0) return n;
+  }
+  return DEFAULT_RUNS_LIMIT;
 }
 
 // List payloads stay lean — output tails ride only on get_run.
@@ -82,8 +109,12 @@ function reply(text, structuredContent) {
 const glyphFor = (status) =>
   status === "passed" ? "✓" : status === "todo" ? "•" : "✗";
 
-export function listText(project, runs) {
+export function listText(project, runs, total = runs.length) {
   if (runs.length === 0) return `No runs recorded for ${project} yet.`;
+  const scope = total > runs.length
+    ? `, last ${runs.length} of ${total} — raise with limit, HIGHBALL_RUNS_LIMIT, ` +
+      "or runs_limit in checks.yml"
+    : "";
   const rows = runs.map((run) => [
     `#${run.index}`,
     run.status === "passed" ? "✓ passed" : "✗ FAILED",
@@ -95,7 +126,7 @@ export function listText(project, runs) {
   ]);
   const widths = rows[0].map((_, col) =>
     Math.max(...rows.map((row) => row[col].length)));
-  const lines = [ `Runs for ${project} (newest first):` ];
+  const lines = [ `Runs for ${project} (newest first${scope}):` ];
   let lastGroup;
   runs.forEach((run, i) => {
     // Group header whenever the work (or its session) changes between
@@ -139,31 +170,68 @@ export async function mcp() {
       (!capability.mimeTypes || capability.mimeTypes.includes(RESOURCE_MIME_TYPE));
   };
 
+  // The client's MCP roots are the one thing a host can tell us about
+  // which repo is open. Best-effort: only asked of clients that advertise
+  // the capability, and a slow or failing answer resolves to nothing.
+  const clientRoots = async () => {
+    try {
+      if (!server.server.getClientCapabilities()?.roots) return [];
+      const { roots } = await server.server.listRoots(undefined, { timeout: 3000 });
+      return roots
+        .map((root) => root.uri)
+        .filter((uri) => uri.startsWith("file:"))
+        .map((uri) => fileURLToPath(uri));
+    } catch {
+      return [];
+    }
+  };
+
+  const projectArg = z.string().optional().describe(
+    "Project slug. Defaults to the repo at `dir`, at the server's cwd, or " +
+    "at the client's MCP roots; when none has a .highball/checks.yml the " +
+    "result lists journaled projects to choose from instead of guessing."
+  );
+  const dirArg = z.string().optional().describe(
+    "Repo root containing .highball/checks.yml. Pass the current working " +
+    "directory when calling from inside a repo."
+  );
+
   registerAppTool(server, "list_runs", {
     title: "Highball runs",
     description:
       "Recent Highball check runs for a project, from the machine-local " +
-      "journal (~/.highball/runs). Renders the runs dashboard widget.",
+      `journal (~/.highball/runs). Newest ${DEFAULT_RUNS_LIMIT} by default. ` +
+      "Renders the runs dashboard widget.",
     inputSchema: {
-      project: z.string().optional()
-        .describe("Project slug; defaults to the current repo's project")
+      project: projectArg,
+      dir: dirArg,
+      limit: z.number().int().min(1).optional().describe(
+        `Max runs to return, newest first (default ${DEFAULT_RUNS_LIMIT}; ` +
+        "HIGHBALL_RUNS_LIMIT or runs_limit in checks.yml also override)"
+      )
     },
     _meta: { ui: { resourceUri: DASHBOARD_URI } }
-  }, async ({ project: explicit }) => {
-    const { project, dir } = resolveProject(explicit);
+  }, async ({ project: explicit, dir: explicitDir, limit }) => {
+    const { project, dir, config } =
+      resolveProject({ project: explicit, dir: explicitDir, roots: await clientRoots() });
     if (!project) {
       const known = journaledProjects();
       return reply(
-        `No project resolved. Journaled projects: ${known.join(", ") || "(none)"}`,
+        "No project resolved: no .highball/checks.yml at the working " +
+          "directory or the client's roots. Pass `project` or `dir`. " +
+          `Journaled projects: ${known.join(", ") || "(none)"}`,
         { projects: known }
       );
     }
-    const runs = readRuns(project).map(summarize);
+    const history = readRuns(project);
+    const max = resolveRunsLimit({ limit, config });
+    const runs = history.slice(0, max).map(summarize);
     return reply(
       uiHost()
-        ? `${runs.length} runs for ${project} — rendered in the dashboard widget.`
-        : listText(project, runs.slice(0, 20)),
-      { project, dir, runs }
+        ? `${runs.length} of ${history.length} runs for ${project} — ` +
+          "rendered in the dashboard widget."
+        : listText(project, runs, history.length),
+      { project, dir, runs, total: history.length, limit: max }
     );
   });
 
@@ -174,13 +242,14 @@ export async function mcp() {
       "captured command output. index counts from 1, newest first.",
     inputSchema: {
       index: z.number().int().min(1).describe("1-based index, newest first"),
-      project: z.string().optional()
-        .describe("Project slug; defaults to the current repo's project")
+      project: projectArg,
+      dir: dirArg
     },
     _meta: { ui: { resourceUri: DASHBOARD_URI } }
-  }, async ({ index, project: explicit }) => {
-    const { project, dir } = resolveProject(explicit);
-    if (!project) return reply("No project resolved.", {});
+  }, async ({ index, project: explicit, dir: explicitDir }) => {
+    const { project, dir } =
+      resolveProject({ project: explicit, dir: explicitDir, roots: await clientRoots() });
+    if (!project) return reply("No project resolved — pass `project` or `dir`.", {});
     const history = readRuns(project);
     const run = history[index - 1];
     if (!run) return reply(`No run #${index} (${history.length} recorded).`, {});
@@ -205,9 +274,10 @@ export async function mcp() {
     },
     _meta: { ui: { resourceUri: DASHBOARD_URI } }
   }, async ({ dir, fast }) => {
-    // No dir given → the current project's repo (from its journal), so
-    // widget-initiated re-runs work from hosts with no useful cwd.
-    const cwd = dir || resolveProject(null).dir || process.cwd();
+    // The widget passes the dir it was grounded with, so re-runs work from
+    // hosts with no useful cwd; otherwise resolve the same way list_runs
+    // does and let the child's own error explain a missing checks.yml.
+    const cwd = dir || resolveProject({ roots: await clientRoots() }).dir || process.cwd();
     const child = spawnSync(
       process.execPath,
       [ BIN_PATH, "run", ...(fast ? [ "--fast" ] : []) ],

package/lib/posthog.js

@@ -0,0 +1,149 @@
+// The runner's telemetry sink. Enforcement is local and always works;
+// this is the witness half, and it is deliberately somebody else's
+// server. An earlier iteration shipped a bespoke Rails dashboard, which
+// meant hosting, auth, and data custody for what is ultimately a
+// warehouse query — so a team points at their own PostHog instead.
+//
+// The whole run leaves in ONE request. The old protocol opened a run,
+// POSTed each result, then PATCHed the status: twenty round trips for an
+// eighteen-rule run. PostHog events are immutable and append-only, which
+// suits a runner that already defers all reporting to after the checks
+// finish — nothing to open, nothing to finalize.
+//
+// Best-effort, always: failures warn and return. A dead analytics
+// endpoint must never block an agent.
+import { hostname, userInfo } from "node:os";
+import { git } from "./git.js";
+
+const TIMEOUT_MS = 15_000;
+
+// Two event types, and deliberately no third. `highball_run` answers
+// "how are runs doing" and `highball_check` answers "which rules are
+// earning their keep"; every question we set out to ask breaks down
+// from one of those.
+export const RUN_EVENT = "highball_run";
+export const CHECK_EVENT = "highball_check";
+
+// Returns true when the batch was accepted, false when reporting was
+// skipped or failed — the caller journals either way.
+export async function reportPosthog({
+  host, key, project, results, hook, fastOnly, startedAt, durationMs, branch,
+  commitSha, version
+}) {
+  try {
+    const batch = buildEvents({
+      project, results, hook, fastOnly, startedAt, durationMs, branch, commitSha,
+      version, distinctId: distinctId()
+    });
+
+    const response = await fetch(new URL("/batch/", host), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ api_key: key, batch }),
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+    if (response.status >= 300) {
+      throw new Error(`${response.status}: ${(await response.text()).slice(0, 200)}`);
+    }
+
+    console.log(`reported ${batch.length} events to ${new URL(host).host}`);
+    return true;
+  } catch (error) {
+    console.error(`highball posthog reporting skipped: ${error.message}`);
+    return false;
+  }
+}
+
+// Pure, so the event shape can be tested without a network or a clock.
+export function buildEvents({
+  project, results, hook, fastOnly, startedAt, durationMs, branch, commitSha,
+  version, distinctId
+}) {
+  const timestamp = startedAt.toISOString();
+  const trigger = fastOnly ? "edit" : "stop";
+  const sessionKey =
+    hook?.session_id || process.env.HIGHBALL_SESSION_KEY || `manual-${hostname()}`;
+
+  // Repeated on every event rather than joined at query time. PostHog has
+  // no joins back to a "run" table, so a breakdown like "failure rate by
+  // rule, on this branch only" needs branch to sit on the check event
+  // itself.
+  const shared = {
+    project,
+    branch,
+    commit: commitSha,
+    trigger,
+    session_key: sessionKey,
+    agent: hook?.session_id ? "claude-code" : "manual",
+    runner_version: version,
+    // PostHog surfaces these in its UI as the sending client.
+    $lib: "highball",
+    $lib_version: version
+  };
+
+  const failed = results.filter((result) => !result.passed);
+  const todo = results.filter((result) => result.todo);
+
+  const events = [ {
+    event: RUN_EVENT,
+    distinct_id: distinctId,
+    timestamp,
+    properties: {
+      ...shared,
+      status: failed.length === 0 ? "passed" : "failed",
+      duration_ms: durationMs,
+      rules_total: results.length,
+      rules_passed: results.length - failed.length - todo.length,
+      rules_failed: failed.length,
+      rules_todo: todo.length,
+      // The denominator for any "how often does rule X fail" question that
+      // spans runs whose rulesets differ.
+      rules_run: results.map((result) => result.rule.id),
+      failed_rules: failed.map((result) => result.rule.id)
+    }
+  } ];
+
+  for (const result of results) {
+    events.push({
+      event: CHECK_EVENT,
+      distinct_id: distinctId,
+      timestamp,
+      properties: {
+        ...shared,
+        rule_id: result.rule.id,
+        rule_name: result.rule.name,
+        status: result.todo ? "todo" : result.passed ? "passed" : "failed",
+        duration_ms: result.durationMs,
+        // A one-line summary, never the log tail. Multi-kilobyte blobs in
+        // event properties bloat the column store and slow every query that
+        // touches it; the full output is already on disk in the journal.
+        summary: summarize(result),
+        command:
+          result.rule.run ?? (result.rule.rubric ? `judge ${result.rule.rubric}` : null)
+      }
+    });
+  }
+
+  return events;
+}
+
+function summarize(result) {
+  if (result.todo) return "planned — not implemented yet";
+  if (result.passed) return null;
+  return result.output.split("\n").find((line) => line.trim())?.trim().slice(0, 120) ?? null;
+}
+
+// Who the run belongs to. The git identity is the one that means anything
+// across machines — the same person on a laptop and a devcontainer should
+// be one person — with the machine as the fallback when git has no
+// identity configured (CI images, fresh containers).
+export function distinctId(env = process.env) {
+  if (env.HIGHBALL_POSTHOG_DISTINCT_ID) return env.HIGHBALL_POSTHOG_DISTINCT_ID;
+  const email = git("git config user.email");
+  if (email) return email;
+  try {
+    return `${userInfo().username}@${hostname()}`;
+  } catch {
+    return `host-${hostname()}`;
+  }
+}

package/lib/run.js

@@ -4,12 +4,21 @@
 // output back). Reporting is the witness half and is best-effort: a dead
 // dashboard must never block the agent.
 import { execSync, spawnSync } from "node:child_process";
-import { loadConfig, resolveReporting, commandFor } from "./config.js";
+import { readFileSync } from "node:fs";
+import { loadConfig, resolvePosthog, commandFor } from "./config.js";
 import { appendRun } from "./journal.js";
-import { git, report } from "./report.js";
+import { readStamp, treeFingerprint, writeStamp } from "./stamp.js";
+import { git } from "./git.js";
+import { reportPosthog } from "./posthog.js";
 import { judge } from "./judge.js";
 import { latestUserPrompt } from "./transcript.js";
 
+// Stamped onto reported events so a query can tell which runner
+// produced them — rule semantics change between releases.
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
+
 export async function run(args) {
   // When an AI-judged rule spawns a judge session inside this repo, the
   // judge inherits the repo's hooks — and its Stop hook would re-enter
@@ -26,6 +35,18 @@ export async function run(args) {
     return 1;
   }
 
+  // --if-changed: a fast hook that also matches Bash fires after every
+  // command, and most commands are reads. Skip outright when the working
+  // tree is exactly where the last run left it. The fingerprint is taken
+  // now and stamped after the checks, so a formatter that rewrites files
+  // mid-run makes the next call run again rather than trust a stale pass.
+  const fingerprint = treeFingerprint();
+  if (args.includes("--if-changed") && fingerprint &&
+      fingerprint === readStamp(config.project)) {
+    console.log("highball: no changes since the last run — skipped");
+    return 0;
+  }
+
   // Rubric rules never join a fast run, even if a config marks one `fast`:
   // LLM latency and cost would be paid on every edit. That belongs at turn
   // end, and the invariant is enforced here rather than left to each repo.
@@ -86,16 +107,20 @@ export async function run(args) {
     results.push({ rule, passed, todo: false, durationMs, output });
   }
 
+  // Stamped pass or fail: after a failure the agent's next reads must not
+  // re-run and re-block; its next edit moves the tree and runs again.
+  if (fingerprint) writeStamp(config.project, fingerprint);
+
   const failures = results.filter((result) => !result.passed);
   const durationMs = Date.now() - startedAt.getTime();
   const branch = git("git branch --show-current");
   const commitSha = git("git rev-parse HEAD");
 
-  const { url, token } = resolveReporting(config);
-  let reportedRunId = null;
-  if (url && token) {
-    reportedRunId = await report({
-      url, token, rules, results, hook, fastOnly, startedAt, branch, commitSha
+  const { host, key } = resolvePosthog(config);
+  if (host && key) {
+    await reportPosthog({
+      host, key, project: config.project, results, hook, fastOnly, startedAt,
+      durationMs, branch, commitSha, version: VERSION
     });
   }
 
@@ -118,7 +143,6 @@ export async function run(args) {
       branch,
       commit: commitSha,
       status: failures.length === 0 ? "passed" : "failed",
-      reported_run_id: reportedRunId,
       results: results.map((result) => ({
         id: result.rule.id,
         name: result.rule.name,

package/lib/stamp.js

@@ -0,0 +1,65 @@
+// Working-tree fingerprint behind `run --fast --if-changed`.
+//
+// Agents in auto mode edit through Bash — sed, heredocs, scripts — so a
+// fast hook matched only on the edit tools never fires for them. Matching
+// Bash too means firing after every command, and most commands are reads.
+// The fingerprint makes those free: HEAD plus every dirty path with its
+// size and mtime, hashed. A further edit to an already-dirty file moves
+// its mtime, so the stamp tracks edits rather than just the set of dirty
+// paths. Stamps live per project outside the repo, like the journal.
+import { createHash } from "node:crypto";
+import { execSync } from "node:child_process";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function stampDir() {
+  return join(homedir(), ".highball", "stamps");
+}
+
+// null outside a git repo: with no way to tell whether anything changed,
+// --if-changed must never skip.
+export function treeFingerprint(cwd = process.cwd()) {
+  const sh = (command) => {
+    try {
+      return execSync(command, { cwd, encoding: "utf8", stdio: [ "ignore", "pipe", "ignore" ] }).trim();
+    } catch {
+      return "";
+    }
+  };
+  const head = sh("git rev-parse HEAD");
+  if (!head) return null;
+
+  const hash = createHash("sha256").update(head).update("\0");
+  const status = sh("git status --porcelain=v1 -z --untracked-files=all");
+  for (const entry of status.split("\0").filter(Boolean)) {
+    hash.update(entry).update("\0");
+    try {
+      const stat = statSync(join(cwd, entry.slice(3)));
+      hash.update(`${stat.size}:${stat.mtimeMs}`);
+    } catch {
+      hash.update("gone");
+    }
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+export function readStamp(project, dir = stampDir()) {
+  try {
+    return readFileSync(join(dir, project), "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+// Best-effort, like the journal: a stamp that fails to write costs one
+// extra fast run, never a failed one.
+export function writeStamp(project, fingerprint, dir = stampDir()) {
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(dir, project), `${fingerprint}\n`);
+  } catch {
+    // ignore
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@profoundry-us/highball",
-  "version": "0.4.0",
-  "description": "Highball runner — local CI for AI coding agents: runs a repo's .highball/checks.yml rules, blocks the agent on failure, and reports runs to a Highball dashboard.",
+  "version": "0.5.0",
+  "description": "Highball runner — local CI for AI coding agents: runs a repo's .highball/checks.yml rules, blocks the agent on failure, and optionally reports runs to PostHog.",
   "keywords": [
     "ai",
     "claude-code",
@@ -12,11 +12,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/profoundry-us/highball-runner.git"
+    "url": "git+https://github.com/profoundry-us/highball.git"
   },
-  "homepage": "https://github.com/profoundry-us/highball-runner#readme",
+  "homepage": "https://github.com/profoundry-us/highball#readme",
   "bugs": {
-    "url": "https://github.com/profoundry-us/highball-runner/issues"
+    "url": "https://github.com/profoundry-us/highball/issues"
   },
   "type": "module",
   "bin": {
@@ -39,7 +39,8 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "yaml": "^2.5.0"
+    "yaml": "^2.5.0",
+    "zod": "^3.25 || ^4.0"
   },
   "license": "MIT"
 }

package/lib/login.js

@@ -1,68 +0,0 @@
-// `highball login` — stores a project token in the machine-local
-// credentials file (~/.highball/credentials.json, host → project →
-// token). The token is read from stdin with --token-stdin (recommended:
-// no shell history, no process listing) or prompted interactively.
-// Tokens never touch the repo tree and are never echoed back.
-import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { createInterface } from "node:readline/promises";
-import { CREDENTIALS_PATH, loadConfig, readCredentials } from "./config.js";
-
-export async function login(args) {
-  const options = parse(args);
-
-  // The local checks.yml, when present, already knows the url + project —
-  // don't make the user repeat what the repo declares.
-  let config = null;
-  try {
-    config = loadConfig();
-  } catch {
-    // Not in a configured repo; url/project must come from flags/prompts.
-  }
-
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const url =
-      options.url ||
-      config?.reporting?.url ||
-      (await rl.question("Highball URL (e.g. https://highball.example.com): "));
-    const project =
-      options.project || config?.project || (await rl.question("Project slug: "));
-    const token = options.tokenStdin
-      ? (await readAllStdin()).trim()
-      : (await rl.question("Project token (input is visible — prefer --token-stdin): ")).trim();
-
-    if (!url || !project || !token) {
-      console.error("highball: url, project, and token are all required.");
-      return 1;
-    }
-
-    const credentials = readCredentials();
-    (credentials[url] ??= {})[project] = token;
-
-    mkdirSync(dirname(CREDENTIALS_PATH), { recursive: true, mode: 0o700 });
-    writeFileSync(CREDENTIALS_PATH, JSON.stringify(credentials, null, 2) + "\n");
-    chmodSync(CREDENTIALS_PATH, 0o600);
-
-    console.log(`stored token for ${project} @ ${url} in ${CREDENTIALS_PATH}`);
-    return 0;
-  } finally {
-    rl.close();
-  }
-}
-
-function parse(args) {
-  const options = { tokenStdin: false };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--url") options.url = args[++i];
-    else if (args[i] === "--project") options.project = args[++i];
-    else if (args[i] === "--token-stdin") options.tokenStdin = true;
-  }
-  return options;
-}
-
-async function readAllStdin() {
-  let text = "";
-  for await (const chunk of process.stdin) text += chunk;
-  return text;
-}

package/lib/report.js

@@ -1,75 +0,0 @@
-// The witness half: best-effort reporting to the Highball app — open
-// run, per-check results, finalize. Payloads mirror the Ruby
-// proto-runner exactly so the ingestion API sees one dialect. Failures
-// here warn and return; they NEVER fail the checks.
-import { execSync } from "node:child_process";
-import { hostname } from "node:os";
-
-// Returns the server's run id on success, null when reporting was
-// skipped or failed — the caller journals it either way.
-export async function report({ url, token, rules, results, hook, fastOnly, startedAt, branch, commitSha }) {
-  try {
-    const base = new URL(url);
-    const request = async (method, path, body) => {
-      const response = await fetch(new URL(path, base), {
-        method,
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(15_000)
-      });
-      if (response.status >= 300) {
-        throw new Error(`${path} -> ${response.status}: ${await response.text()}`);
-      }
-      return response.json();
-    };
-
-    const opened = await request("POST", "/api/v1/runs", {
-      agent: hook.session_id ? "claude-code" : "manual",
-      session_key:
-        hook.session_id || process.env.HIGHBALL_SESSION_KEY || `manual-${hostname()}`,
-      trigger: fastOnly ? "edit" : "stop",
-      branch,
-      commit_sha: commitSha,
-      rules_snapshot: rules,
-      started_at: startedAt.toISOString()
-    });
-    const runId = opened.run_id;
-
-    for (const result of results) {
-      await request("POST", `/api/v1/runs/${runId}/results`, {
-        check_key: result.rule.id,
-        name: result.rule.name,
-        status: result.todo ? "todo" : result.passed ? "passed" : "failed",
-        duration_ms: result.durationMs,
-        // Full logs stay local; the tail is enough to read a failure on
-        // the dashboard without shipping megabytes per keystroke.
-        log_tail: result.passed ? null : result.output.slice(-4000),
-        summary: result.todo
-          ? "planned — not implemented yet"
-          : result.passed
-            ? null
-            : result.output.split("\n")[0]?.trim().slice(0, 120)
-      });
-    }
-
-    await request("PATCH", `/api/v1/runs/${runId}`, {
-      status: results.every((result) => result.passed) ? "passed" : "failed"
-    });
-    console.log(`reported to ${base.host} (run ${runId})`);
-    return runId;
-  } catch (error) {
-    console.error(`highball reporting skipped: ${error.message}`);
-    return null;
-  }
-}
-
-export function git(command) {
-  try {
-    return execSync(`${command} 2>/dev/null`, { encoding: "utf8" }).trim();
-  } catch {
-    return "";
-  }
-}