@profoundry-us/highball 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,246 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Release dates are the day the version was published to npm.
+
+## [Unreleased]
+
+## [0.7.0] - 2026-09-10
+
+### Added
+
+- Per-rule timeouts. Every rule runs under a wall-clock budget: 8s for a
+  `fast` rule, 60s otherwise, 300s for an AI-judged rule. Raise a kind for the
+  whole repo with a top-level `timeouts:` block (`fast:`, `full:`, `judge:`),
+  or one rule with `timeout:`; both are seconds. A rule past its budget is
+  killed together with every process it started and fails with a message
+  naming the budget it hit. (#21)
+- The journal records a run from the moment it starts and rewrites the record
+  after every rule, so a run that dies mid-way still shows how far it got. A
+  runner stopped by a signal (a hook timeout, a closed terminal, Ctrl-C) kills
+  the rule it was in, journals the run as `killed`, and exits 1. The CLI, the
+  MCP text and the dashboard widget label `running`, `killed` and `timed out`.
+  (#21)
+- Publishing a tag now also creates its GitHub release, with notes generated
+  from the merged pull requests. 0.7.0 is the first release with a page. (#22)
+- This changelog.
+
+### Changed
+
+- `init` writes a 120-second timeout on the fast hook it scaffolds; Claude
+  Code's default was ten minutes. (#21)
+- The check loop is asynchronous, which is what lets the runner enforce its
+  own budgets and respond to signals. Rule output is still captured the same
+  way; the AI judge keeps its synchronous spawn and receives the budget as a
+  timeout. (#21)
+- The onboarding guide tells the agent to install with the package manager
+  the repo's lockfile names (yarn, pnpm or npm), and what to do when yarn
+  refuses on the repo's own `engines` field. The README lists all three
+  install commands. (#18)
+- Highball's own fast rule is scoped to changed files: it parses every changed
+  JavaScript file and runs the changed modules' unit tests, leaving the suites
+  that spawn the CLI to turn end. The README states the targets the budgets
+  serve: fast lane under 2s, full suite under 30s. (#21)
+
+### Fixed
+
+- The test suite no longer reports fixture runs to the PostHog project named in
+  the developer's environment. (#21)
+
+**Behaviour change for consuming repos:** a `fast: true` rule that takes
+longer than 8 seconds now fails as timed out. Give it its own `timeout:`, or
+scope it to `HIGHBALL_CHANGED_FILES`.
+
+## [0.6.1] - 2026-09-08
+
+### Changed
+
+- `package.json` carries the homepage, https://highball.profoundry.us, so the
+  npm page links to the site. The README links there too. (#16)
+
+## [0.6.0] - 2026-09-04
+
+### Added
+
+- Three ways to switch a repo's checks off, none of them silent: `enabled:
+  false` in `checks.yml` for everyone who clones the repo; `HIGHBALL_DISABLED`
+  for one machine; and a `.highball/disabled` marker file for one checkout,
+  gitignored by the `.highball/.gitignore` that `init` now writes and re-read
+  on every run, so it toggles inside a live agent session with no restart.
+  Text in the marker comes back as the reason on every run. (#10, #13)
+- Continuous integration runs the test suite on pull requests and pushes to
+  `main`, on Node 18 and 22. (#11)
+
+### Changed
+
+- `--if-changed` stamps are per checkout rather than per project, so a git
+  worktree or a second clone never skips a run because the other one passed.
+  (#9)
+- `enabled:` accepts only a real boolean; `enabled: no` and `enabled: "false"`
+  are errors rather than checks quietly left on. `HIGHBALL_DISABLED=0`,
+  `false`, `no`, `off` and empty mean not disabled. (#10)
+- The README says when each off switch takes effect, and documents keeping the
+  PostHog key in the environment instead of the repo. (#8, #12)
+
+## [0.5.0] - 2026-09-03
+
+### Added
+
+- Runs report to PostHog: `reporting.posthog` in `checks.yml` (or
+  `HIGHBALL_POSTHOG_KEY` in the environment) sends one `highball_run` event
+  per run and one `highball_check` event per rule, in a single batch after
+  the checks finish. The project key is write-only by design, so it is
+  committed config with no login step. Dashboard queries ship in
+  `docs/posthog-queries.sql`. (#4)
+- The fast hook `init` scaffolds matches `Bash` as well as `Write|Edit`, since
+  agents in auto mode edit through the shell, and runs with `--if-changed`,
+  which fingerprints the working tree and exits at once when nothing moved
+  since the last run. (#7)
+- The MCP server resolves the current project from its `project` or `dir`
+  argument, a `checks.yml` at its working directory, or the client's roots,
+  and never falls back to another repo's journal. When none names a repo, the
+  widget offers the journaled projects as a picker. (#7)
+- A regression test for the stdin deadline, timing the runner process rather
+  than the pipeline it sits in. (#3)
+
+### Removed
+
+- The hosted dashboard sink and everything that served it: `highball login`,
+  `~/.highball/credentials.json`, `reporting.url`, `HIGHBALL_URL` and
+  `HIGHBALL_TOKEN`. Enforcement was always local; the witness half is now a
+  PostHog project the team owns. A `checks.yml` still carrying
+  `reporting.url` prints a warning on every run and reports nowhere. (#5)
+
+### Changed
+
+- Package metadata points at the renamed repository, profoundry-us/highball.
+  (#6)
+
+## [0.4.1] - 2026-08-19
+
+### Fixed
+
+- `zod` is a declared dependency. `lib/mcp.js` imported it while it was only
+  present by hoisting, so `highball mcp` failed to start under pnpm, Yarn PnP
+  and nohoist layouts. (#2)
+
+## [0.4.0] - 2026-08-15
+
+### Added
+
+- AI-judged rules are a first-class rule type. A rule declares `rubric:`
+  instead of `run:`; the runner bundles the changed files the rubric's front
+  matter selects, applies it through headless Claude, and returns the same
+  pass/fail contract as any other rule. Rubric rules never join a `--fast`
+  run, never pass through `exec.via`, and never spawn the model when no
+  changed file matches. Packs keep the rubrics; the engine lives here. (#1)
+
+## [0.3.2] - 2026-08-15
+
+### Fixed
+
+- The runner no longer hangs when stdin is open but silent. It read hook
+  payloads to EOF, which never returned when invoked from a pipeline that
+  neither wrote nor closed; the read now races a 400ms deadline and degrades
+  to a run with no session context.
+- `bin/highball.js` is marked executable in git, so directory installs work
+  as well as tarball installs.
+
+## [0.3.1] - 2026-08-15
+
+### Changed
+
+- `init` scaffolds the scoped command, `npx @profoundry-us/highball`, into
+  `.claude/settings.json`. The unscoped name belongs to an unrelated package,
+  and a committed hook is the wrong place to leave that ambiguity. Every
+  example in the docs is scoped as well, including the MCP registration.
+- The onboarding guide's container guidance is its own section, with the
+  probes to run and the four traps that had each cost a real onboarding:
+  `-T`, `--workdir`, self-orchestrating targets, and host-only tools.
+
+## [0.3.0] - 2026-08-14
+
+### Added
+
+- `highball mcp`: an MCP server over stdio exposing `list_runs`, `get_run` and
+  `run_checks`, each carrying an MCP Apps dashboard widget. Hosts that render
+  Apps get an interactive run list with click-through detail, expandable
+  per-rule output, and re-run buttons; every other host gets the same picture
+  as aligned plain text, decided by the client's declared capabilities.
+- A widget development harness, `npm run harness`, serving the real dashboard
+  against live journal data.
+- Every list view shows each run's total duration, and runs are grouped under
+  the agent prompt that produced them, read from the hook's transcript.
+- The journal records each rule's command, so quiet rules still have
+  something to show; rows with nothing to reveal are no longer disclosures.
+- Publishing from a pushed `v*` tag through npm trusted publishing (OIDC),
+  gated on the tag matching `package.json`, the tests passing, and the
+  tarball carrying the widget.
+
+## [0.2.2] - 2026-08-11
+
+Not published to npm.
+
+### Changed
+
+- The run detail view uses the same column formatter as the list.
+
+## [0.2.1] - 2026-08-11
+
+Not published to npm.
+
+### Added
+
+- `highball runs <n> --logs` prints every rule's captured output; the journal
+  keeps the last 10KB per rule, pass or fail.
+
+### Changed
+
+- `highball runs` output is colored when writing to a terminal (`NO_COLOR`
+  respected, `FORCE_COLOR` overrides), with status columns right-aligned.
+
+## [0.2.0] - 2026-08-11
+
+Not published to npm.
+
+### Added
+
+- A local run journal at `~/.highball/runs/<project>.jsonl`, written on every
+  run whether or not reporting is configured and pruned to the last 200 runs,
+  and `highball runs` to list recent runs and show one run's detail.
+
+## [0.1.0] - 2026-08-11
+
+### Added
+
+- The runner: `highball run [--fast]` executes the rules in
+  `.highball/checks.yml`, prints progress, and exits 2 with the failures on
+  stderr, the contract a Claude Code Stop hook reads as "block the agent and
+  hand it the output". Rules marked `fast: true` run on every edit; `todo:
+  true` declares a rule that is tracked but never fails.
+- The execution context: `exec.via` wraps every rule in a declared command
+  (a container, say) and a rule opts out with `exec: host`. The runner owns
+  git and hands every rule the changed-file list in `HIGHBALL_CHANGED_FILES`.
+- `highball init` scaffolds `checks.yml` and the Claude Code hooks, never
+  overwriting what exists.
+- `highball onboard` prints a setup guide written for the repo's own AI agent.
+- `highball login`, for the hosted dashboard of the time.
+- MIT license and registry metadata.
+
+[Unreleased]: https://github.com/profoundry-us/highball/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/profoundry-us/highball/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/profoundry-us/highball/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/profoundry-us/highball/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/profoundry-us/highball/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/profoundry-us/highball/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/profoundry-us/highball/compare/de0d5a8...v0.4.0
+[0.3.2]: https://github.com/profoundry-us/highball/compare/aa148c1...de0d5a8
+[0.3.1]: https://github.com/profoundry-us/highball/compare/e0e54d4...aa148c1
+[0.3.0]: https://github.com/profoundry-us/highball/compare/292dbbd...e0e54d4
+[0.2.2]: https://github.com/profoundry-us/highball/compare/99d20c1...292dbbd
+[0.2.1]: https://github.com/profoundry-us/highball/compare/e123bc7...99d20c1
+[0.2.0]: https://github.com/profoundry-us/highball/compare/91c6b6d...e123bc7
+[0.1.0]: https://github.com/profoundry-us/highball/commits/91c6b6d

package/ONBOARDING.md

@@ -16,10 +16,27 @@ yourself.
 
 `npx @profoundry-us/highball --help` must work (Node >= 18, package installed as a dev
 dependency). If it doesn't, ask your human whether to install from the npm
-registry (`npm install --save-dev @profoundry-us/highball`) or from a
-local tarball path they provide. In a repo with no `package.json`, create
-a minimal private one first (`{ "name": "<repo>", "private": true }`) and
-gitignore `node_modules/` if it isn't already.
+registry or from a local tarball path they provide. Install with the package
+manager the repo already uses — the lockfile tells you which, and mixing
+managers leaves two lockfiles that disagree:
+
+| Lockfile present | Install command |
+|---|---|
+| `yarn.lock` | `yarn add -D @profoundry-us/highball` |
+| `pnpm-lock.yaml` | `pnpm add -D @profoundry-us/highball` |
+| `package-lock.json`, or none | `npm install --save-dev @profoundry-us/highball` |
+
+If the install stops with `The engine "node" is incompatible with this
+module`, the repo pins a Node version in its own `engines` field and you are
+running a different one (yarn treats that as a hard error; npm only warns).
+Switch to the pinned version with whatever the repo already uses (`.nvmrc`,
+`.node-version`, `.tool-versions`, `volta`) and retry. Don't pass
+`--ignore-engines` and don't edit the `engines` field — if no version manager
+is set up, ask your human.
+
+In a repo with no `package.json`, create a minimal private one first
+(`{ "name": "<repo>", "private": true }`) and gitignore `node_modules/` if it
+isn't already.
 
 **Never run bare `npx highball` where the package is NOT installed**: the
 unscoped npm name `highball` belongs to an unrelated package, and npx
@@ -127,6 +144,7 @@ checks:
     name: Unit tests (offline)
     run: just test-unit               # orchestrates its own docker exec
     exec: host                        # → must run on the host
+    timeout: 300                      # seconds; the default for a full rule is 60
 
   - id: coverage-ratchet
     name: Coverage never decreases
@@ -145,6 +163,14 @@ Decision rules:
 - The runner exports `HIGHBALL_CHANGED_FILES` (newline-separated,
   repo-relative) to every rule — scripts that want changed-only behavior
   can read it instead of shelling out to git.
+- Every rule runs under a budget and is killed past it: 8s for a `fast`
+  rule, 60s otherwise, 300s for an AI-judged one. Time the repo's test
+  command before you write its rule, and give it an honest `timeout:`
+  (seconds) if it needs more — a suite marked `fast` needs one for sure.
+  Raise a whole kind with a top-level `timeouts:` block (`fast:`,
+  `full:`, `judge:`). A rule that times out fails and says which budget
+  it hit; do not answer that by raising the number without asking your
+  human whether the rule hung.
 
 ## 4. Telemetry — **human**, and optional
 

package/README.md

@@ -1,5 +1,7 @@
 # @profoundry-us/highball
 
+**Website:** [highball.profoundry.us](https://highball.profoundry.us) · [Getting started](https://highball.profoundry.us/#getting-started)
+
 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
@@ -14,7 +16,14 @@ endpoint means checks still run and still block, they just aren't recorded.
 
 ## Install
 
-Published releases: `npm install --save-dev @profoundry-us/highball`.
+Published releases, with whichever package manager the repo's lockfile says
+it uses:
+
+```bash
+yarn add -D @profoundry-us/highball
+npm install --save-dev @profoundry-us/highball
+pnpm add -D @profoundry-us/highball
+```
 
 **Always use the scoped name.** The unscoped npm name `highball` belongs to
 an unrelated package, so a bare `npx highball` — in a committed hook, a
@@ -35,6 +44,9 @@ installing the package, tell the repo's Claude Code agent:
 
 > Run `npx @profoundry-us/highball onboard` and follow the instructions.
 
+The site's [Getting started](https://highball.profoundry.us/#getting-started)
+section shows this route and the manual one side by side.
+
 [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, and verifying all four proofs —
@@ -79,10 +91,16 @@ reporting:
 exec:
   via: docker compose exec -T app
 
+# Wall-clock budgets in seconds; a rule past its budget is killed and
+# fails as "timed out". Defaults: fast 8, full 60, judge 300.
+timeouts:
+  full: 120
+
 checks:
   - id: unit-tests
     name: Unit tests
     run: bundle exec rspec spec        # runs through exec.via
+    timeout: 300                       # this rule's own budget
 
   - id: js-syntax
     name: Playback JS parses
@@ -103,6 +121,46 @@ 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.
 
+## Timeouts
+
+Every rule runs under a wall-clock budget. A rule that runs past it is
+killed — the whole process tree, so a hung test runner started by `npm`
+started by a shell doesn't live on after the run has given up on it — and
+fails with the reason:
+
+```
+→ Unit tests ... TIMED OUT (8.0s)
+
+### Unit tests (unit-tests) failed. Fix before finishing:
+…
+highball: timed out after 8s and was killed. Its budget is `timeouts.fast: 8`
+in .highball/checks.yml — raise it there if this rule legitimately needs
+longer, or find what hung.
+```
+
+The defaults are deliberately tight: **8s** for a rule marked `fast: true`,
+**60s** for everything else, **300s** for an AI-judged rule. A fast rule runs
+after every agent edit, and a rule worth that is one that finishes before the
+agent's next thought — 8s is generous for a lint or a grep and far too short
+for a suite, which is the point: a suite marked fast has to earn it with its
+own `timeout:`. Raise a kind for the whole repo with `timeouts:`, or give
+one rule its own `timeout:`; both are seconds. Either way the number is a
+decision in `checks.yml`, not a mystery.
+
+The budgets are kill switches, not targets. The targets, for a small project:
+the fast lane under **2s**, the full suite under **30s**. A fast rule should
+look only at what changed — the runner hands every rule the changed-file
+list in `HIGHBALL_CHANGED_FILES`, so "parse the changed files and run the
+changed modules' own tests" is a short script — and a full suite that can't
+make 30s should scope itself the same way rather than run long. Highball's
+own `.highball/checks/tests-for-changed` is the worked example.
+
+The budget is what turns a hang into evidence. Without one, a rule that never
+returns holds the hook open until Claude Code kills it, and (before 0.7) the
+run was journaled nowhere — "the tests hang sometimes" had nothing to point
+at. The hook timeouts `init` writes are backstops for the runner itself, not
+budgets for rules: they should only ever fire if the runner is wedged.
+
 ## Turning it off
 
 Three switches, differing in who they affect and — the part that usually
@@ -316,6 +374,16 @@ 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.
 
+A run is journaled from the moment it starts, and rewritten after every rule,
+so the record is always as current as the run. A run that ends the ordinary
+way is `passed` or `failed`. One still marked `running` is either live
+right now or died without getting to say so — a crash, a `kill -9`. One
+marked `killed` was stopped in the middle of a rule (Claude Code giving up
+on the hook, a closed terminal, Ctrl-C); the runner took the rule's process
+tree down with it and journaled which rule it was in. A rule that ran past
+its budget is `failed` with `timed_out`. None of these used to leave a
+trace, which is exactly when a trace was needed.
+
 ## Roadmap
 
 Built-in generic rules (spec pairing, focused-spec detection, diff budgets)

package/assets/dashboard.html

@@ -52,6 +52,8 @@
   .chip.passed { color: var(--green); background: var(--green-bg); }
   .chip.failed { color: var(--red); background: var(--red-bg); }
   .chip.todo { color: var(--muted); background: var(--gray-bg); }
+  .chip.running { color: var(--muted); background: var(--gray-bg); }
+  .chip.killed { color: var(--red); background: var(--red-bg); }
   .mono { font-family: ui-monospace, Menlo, monospace; font-size: 12px; }
   details.rule {
     border: 1px solid var(--line); border-radius: 8px; background: var(--card);
@@ -158,8 +160,21 @@
     if (s < 86400) return `${Math.round(s / 3600)}h ago`;
     return `${Math.round(s / 86400)}d ago`;
   }
-  function chip(status) {
-    return `<span class="chip ${esc(status)}">${esc(status)}</span>`;
+  function chip(status, label = status) {
+    return `<span class="chip ${esc(status)}">${esc(label)}</span>`;
+  }
+  // "running" is a run the journal saw start and not finish — live right
+  // now, or one that died without saying so. "killed" is one the runner
+  // was stopped in the middle of.
+  function runLabel(status) {
+    return status === "passed" ? "✓ passed"
+      : status === "running" ? "… running"
+      : status === "killed" ? "✗ killed"
+      : "✗ failed";
+  }
+  // A failure the runner caused, rather than the rule, says so.
+  function ruleLabel(result) {
+    return result.timed_out ? "timed out" : result.killed ? "killed" : result.status;
   }
   function tally(results) {
     const counts = {};
@@ -217,7 +232,7 @@
       lastGroup = group;
       return heading + `
       <div class="row" data-index="${run.index}">
-        <span class="chip ${esc(run.status)}">${run.status === "passed" ? "✓ passed" : "✗ failed"}</span>
+        <span class="chip ${esc(run.status)}">${runLabel(run.status)}</span>
         <span class="when">${timeAgo(run.started_at)}</span>
         <span class="meta">${run.trigger === "edit" ? "fast" : "full"}</span>
         <span class="mono">${esc(run.branch || "-")}</span>
@@ -252,7 +267,7 @@
         `<span class="glyph ${esc(result.status)}">${result.status === "passed" ? "✓" : result.status === "todo" ? "•" : "✗"}</span>` +
         `<span>${esc(result.name)}</span>` +
         `<span class="spacer"></span>` +
-        chip(result.status) +
+        chip(result.status, ruleLabel(result)) +
         `<span class="meta">${duration}</span>`;
 
       // What the panel can actually show. Quiet rules (the AI judges print

package/lib/config.js

@@ -37,6 +37,23 @@ export function loadConfig(root = process.cwd()) {
           "`run:`, `rubric:`, or `todo: true`."
       );
     }
+    if (rule.timeout !== undefined) {
+      assertSeconds(rule.timeout, `rule \`${rule.id ?? "(unnamed)"}\` has \`timeout:\``);
+    }
+  }
+  if (config.timeouts !== undefined) {
+    if (typeof config.timeouts !== "object" || config.timeouts === null) {
+      throw new Error(`${CONFIG_PATH}: \`timeouts:\` must be a block of fast/full/judge seconds.`);
+    }
+    for (const [ kind, value ] of Object.entries(config.timeouts)) {
+      if (!(kind in DEFAULT_TIMEOUTS)) {
+        throw new Error(
+          `${CONFIG_PATH}: \`timeouts.${kind}\` is not a thing — ` +
+            `the kinds are ${Object.keys(DEFAULT_TIMEOUTS).join(", ")}.`
+        );
+      }
+      assertSeconds(value, `\`timeouts.${kind}:\``);
+    }
   }
   // The dashboard sink is gone; PostHog is the only telemetry path. A repo
   // carrying the old block would otherwise report nowhere and say nothing
@@ -115,6 +132,37 @@ export function resolvePosthog(config, env = process.env) {
   return { host, key };
 }
 
+// Wall-clock budgets per rule, in seconds. A fast rule is one worth running
+// after every edit, and a rule worth that is one that finishes before the
+// agent's next thought — 8s is generous for a lint or a grep and far too
+// short for a suite, which is the point: a suite marked fast has to earn
+// it with its own `timeout:`. Full rules get a minute by default; teams
+// with a long suite raise `timeouts.full` and own the number. AI judges
+// wait on a model, so they get their own, longer default.
+//
+// The budget is what turns a hang into evidence. Without one, a rule that
+// never returns holds the hook until Claude Code kills it, and the run is
+// journaled nowhere.
+export const DEFAULT_TIMEOUTS = { fast: 8, full: 60, judge: 300 };
+
+function assertSeconds(value, where) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      `${CONFIG_PATH}: ${where} must be a positive number of seconds, not ` +
+        `\`${value}\` (${typeof value}).`
+    );
+  }
+}
+
+// Milliseconds a rule may run before the runner kills it: the rule's own
+// `timeout:` if it has one, else the default for its kind.
+export function timeoutFor(rule, config = {}) {
+  const timeouts = { ...DEFAULT_TIMEOUTS, ...(config.timeouts ?? {}) };
+  const seconds = rule.timeout ??
+    (rule.rubric ? timeouts.judge : rule.fast ? timeouts.fast : timeouts.full);
+  return seconds * 1000;
+}
+
 // The execution-context decision (ADR 202608): rule definitions stay
 // environment-agnostic; the checkout declares `exec.via` once and every
 // rule runs through it unless it opts out with `exec: host`. No declared

package/lib/init.js

@@ -28,6 +28,13 @@ project: ${project}
 #     host: https://us.i.posthog.com
 #     project_key: phc_your_key
 
+# Wall-clock budgets, in seconds. A rule past its budget is killed along
+# with everything it started, fails with "timed out", and is journaled
+# that way. Defaults: fast 8, full 60, judge 300. Raise a kind here, or
+# give one rule its own \`timeout:\` below.
+# timeouts:
+#   full: 120
+
 # 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
 # with \`exec: host\`. Omit entirely for host-based setups.
@@ -38,6 +45,7 @@ checks:
   # - id: unit-tests
   #   name: Unit tests
   #   run: npm test
+  #   timeout: 300
 
   # - id: lint
   #   name: Lint & formatting
@@ -52,6 +60,11 @@ checks:
 // 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.
+//
+// The hook timeouts are backstops, not budgets: the runner times out each
+// rule itself (`timeouts:` in checks.yml) and journals the result, so the
+// hook's own limit should only ever fire if the runner is somehow wedged.
+// Without one, Claude Code's default for a fast hook is ten minutes.
 const HOOKS_JSON = {
   hooks: {
     PostToolUse: [
@@ -59,7 +72,8 @@ const HOOKS_JSON = {
         matcher: "Write|Edit|Bash",
         hooks: [{
           type: "command",
-          command: "npx @profoundry-us/highball run --fast --if-changed"
+          command: "npx @profoundry-us/highball run --fast --if-changed",
+          timeout: 120
         }]
       }
     ],

package/lib/journal.js

@@ -21,13 +21,28 @@ export function journalPath(project, dir = journalDir()) {
   return join(dir, `${project}.jsonl`);
 }
 
+// A record carrying an `id` replaces its earlier self rather than adding a
+// line: the runner writes a run when it starts and again after every rule,
+// so a run cut off mid-way still shows how far it got — one record per run
+// either way. Records without an id (older runners, tests) simply append.
 export function appendRun(project, record, dir = journalDir()) {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   const path = journalPath(project, dir);
   const lines = existsSync(path)
     ? readFileSync(path, "utf8").split("\n").filter(Boolean)
     : [];
-  lines.push(JSON.stringify(record));
+  const line = JSON.stringify(record);
+  const at = record.id === undefined ? -1 : lines.findIndex((existing) => {
+    // The substring test keeps this cheap; the parse keeps it honest.
+    if (!existing.includes(record.id)) return false;
+    try {
+      return JSON.parse(existing).id === record.id;
+    } catch {
+      return false;
+    }
+  });
+  if (at === -1) lines.push(line);
+  else lines[at] = line;
   writeFileSync(path, lines.slice(-MAX_RUNS).join("\n") + "\n");
 }
 

package/lib/judge.js

@@ -137,6 +137,7 @@ export function judge(options) {
   const {
     rubricPath,
     changed,
+    timeoutMs,
     spawn = spawnSync,
     exists = existsSync,
     read = (path) => readFileSync(path, "utf8")
@@ -166,10 +167,23 @@ export function judge(options) {
       input: buildPrompt(body, bundle),
       encoding: "utf8",
       env: { ...process.env, HIGHBALL_JUDGE: "1" },
-      maxBuffer: 32 * 1024 * 1024
+      maxBuffer: 32 * 1024 * 1024,
+      // The runner's budget for this rule. A judge that never answers —
+      // a stalled model, a CLI waiting on a login prompt — is a failed
+      // rule with a reason, not a hook held open until something else
+      // kills it.
+      timeout: timeoutMs,
+      killSignal: "SIGKILL"
     }
   );
 
+  if (child.error?.code === "ETIMEDOUT") {
+    return {
+      passed: false,
+      timedOut: true,
+      output: `AI judge gave no verdict within ${timeoutMs / 1000}s.`
+    };
+  }
   if (child.error?.code === "ENOENT") {
     return {
       passed: false,

package/lib/mcp.js

@@ -109,6 +109,18 @@ function reply(text, structuredContent) {
 const glyphFor = (status) =>
   status === "passed" ? "✓" : status === "todo" ? "•" : "✗";
 
+const runLabel = (status) =>
+  status === "passed" ? "✓ passed"
+    : status === "running" ? "… running"
+      : status === "killed" ? "✗ KILLED"
+        : "✗ FAILED";
+
+// A failure the runner caused, rather than the rule, says so.
+const ruleLabel = (result) =>
+  result.timed_out ? "failed (timed out)"
+    : result.killed ? "failed (killed)"
+      : result.status;
+
 export function listText(project, runs, total = runs.length) {
   if (runs.length === 0) return `No runs recorded for ${project} yet.`;
   const scope = total > runs.length
@@ -117,7 +129,7 @@ export function listText(project, runs, total = runs.length) {
     : "";
   const rows = runs.map((run) => [
     `#${run.index}`,
-    run.status === "passed" ? "✓ passed" : "✗ FAILED",
+    runLabel(run.status),
     run.trigger === "edit" ? "fast" : "full",
     run.branch || "-",
     run.duration_ms != null ? `${(run.duration_ms / 1000).toFixed(1)}s` : "-",
@@ -148,7 +160,7 @@ export function detailText(project, index, run) {
   const rules = run.results.map((result) => {
     const duration = result.duration_ms != null
       ? ` (${(result.duration_ms / 1000).toFixed(1)}s)` : "";
-    let line = `  ${glyphFor(result.status)} ${result.name} — ${result.status}${duration}`;
+    let line = `  ${glyphFor(result.status)} ${result.name} — ${ruleLabel(result)}${duration}`;
     if (result.status === "failed" && result.output_tail) {
       line += "\n" + result.output_tail.split("\n").map((l) => `      ${l}`).join("\n");
     }

package/lib/run.js

@@ -3,11 +3,12 @@
 // contract: a Stop hook reading exit 2 blocks the agent and feeds the
 // output back). Reporting is the witness half and is best-effort: an
 // unreachable PostHog must never block the agent.
-import { execSync, spawnSync } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import {
   CONFIG_PATH, DISABLED_MARKER, disabledByEnv, disabledByMarker,
-  loadConfig, resolvePosthog, commandFor
+  loadConfig, resolvePosthog, commandFor, timeoutFor
 } from "./config.js";
 import { appendRun } from "./journal.js";
 import { readStamp, treeFingerprint, writeStamp } from "./stamp.js";
@@ -96,48 +97,121 @@ export async function run(args) {
   const startedAt = new Date();
   const results = [];
 
-  for (const rule of rules) {
-    process.stdout.write(`→ ${rule.name} ... `);
+  // Everything the journal record needs that doesn't change during the
+  // run, gathered once: the record is written many times (below), and the
+  // transcript read behind `work` is not free.
+  const context = {
+    id: randomUUID(),
+    project: config.project,
+    startedAt,
+    fastOnly,
+    session: hook.session_id || null,
+    work: latestUserPrompt(hook.transcript_path),
+    branch: git("git branch --show-current"),
+    commit: git("git rev-parse HEAD")
+  };
 
-    // Placeholder rules are tracked, not run: they report as "todo" so
-    // the widget and PostHog show the full intended ruleset, and they can never
-    // fail a run — an aspiration shouldn't block anyone.
-    if (rule.todo) {
-      console.log("todo (not implemented yet)");
-      results.push({ rule, passed: true, todo: true, durationMs: null, output: "" });
-      continue;
+  // The journal sees the run from its first moment, not its last. One
+  // record per run, written when the run starts and rewritten after every
+  // rule (same id, so it replaces itself), so a run that never reaches the
+  // end — a hook timeout, a killed terminal, a crash — still leaves behind
+  // exactly how far it got and which rule it was in. Before this, a run
+  // that died mid-rule was journaled nowhere at all, and "npm test hangs
+  // sometimes" had no evidence to point at. Failures to write never fail
+  // the checks, same policy as reporting.
+  const journal = (status) => {
+    try {
+      appendRun(config.project, journalRecord(context, status, results));
+    } catch (error) {
+      console.error(`highball journal skipped: ${error.message}`);
     }
+  };
+  journal("running");
 
-    // Rubric rules run in-process instead of shelling out: the judge needs
-    // the `claude` CLI, which lives on the host, so it bypasses `exec.via`
-    // by construction rather than by annotation.
-    if (rule.rubric) {
+  // A stopped runner — Claude Code giving up on the hook, a Ctrl-C, a
+  // closed terminal — takes the rule it was in down with it and says so in
+  // the journal, instead of leaving a hung suite running on unowned and a
+  // run that looks like it never happened. `current` is the child of the
+  // rule executing right now; `stopped` remembers the signal so the loop
+  // can wind down rather than start the next rule.
+  let current = null;
+  let stopped = null;
+  const onSignal = (signal) => {
+    if (stopped) return;
+    stopped = signal;
+    if (current) killTree(current);
+  };
+  const SIGNALS = [ "SIGTERM", "SIGINT", "SIGHUP" ];
+  for (const signal of SIGNALS) process.on(signal, onSignal);
+
+  try {
+    for (const rule of rules) {
+      process.stdout.write(`→ ${rule.name} ... `);
+
+      // Placeholder rules are tracked, not run: they report as "todo" so
+      // the widget and PostHog show the full intended ruleset, and they can never
+      // fail a run — an aspiration shouldn't block anyone.
+      if (rule.todo) {
+        console.log("todo (not implemented yet)");
+        results.push({ rule, passed: true, todo: true, durationMs: null, output: "" });
+        journal("running");
+        continue;
+      }
+
+      const timeoutMs = timeoutFor(rule, config);
       const t0 = process.hrtime.bigint();
-      const { passed, output } = judge({ rubricPath: rule.rubric, changed });
+      let outcome;
+
+      // Rubric rules run in-process instead of shelling out: the judge needs
+      // the `claude` CLI, which lives on the host, so it bypasses `exec.via`
+      // by construction rather than by annotation.
+      if (rule.rubric) {
+        outcome = judge({ rubricPath: rule.rubric, changed, timeoutMs });
+      } else {
+        // The runner owns git (ADR 202608): check scripts get the changed
+        // list handed to them and stay pure analyzers — no git, no network
+        // required in their execution context (which may be a container).
+        const child = await runCommand(commandFor(rule, config), {
+          env: { ...process.env, HIGHBALL_CHANGED_FILES: changed },
+          timeoutMs,
+          onSpawn: (spawned) => { current = spawned; }
+        });
+        current = null;
+        outcome = { passed: child.status === 0, output: child.output, timedOut: child.timedOut };
+      }
+
       const durationMs = Math.round(Number(process.hrtime.bigint() - t0) / 1e6);
+      const result = { rule, passed: outcome.passed, todo: false, durationMs, output: outcome.output };
 
-      console.log(`${passed ? "passed" : "FAILED"} (${(durationMs / 1000).toFixed(1)}s)`);
-      results.push({ rule, passed, todo: false, durationMs, output });
-      continue;
-    }
+      if (stopped) {
+        // Whatever the child reported, it reported because we killed it.
+        result.passed = false;
+        result.killed = true;
+        result.output = `${outcome.output}\n\nhighball was stopped (${stopped}) while this rule was running.`;
+        console.log(`KILLED (${(durationMs / 1000).toFixed(1)}s)`);
+        results.push(result);
+        break;
+      }
 
-    const command = commandFor(rule, config);
-    const t0 = process.hrtime.bigint();
-    // The runner owns git (ADR 202608): check scripts get the changed
-    // list handed to them and stay pure analyzers — no git, no network
-    // required in their execution context (which may be a container).
-    const child = spawnSync(`${command} 2>&1`, {
-      shell: true,
-      encoding: "utf8",
-      env: { ...process.env, HIGHBALL_CHANGED_FILES: changed },
-      maxBuffer: 32 * 1024 * 1024
-    });
-    const durationMs = Math.round(Number(process.hrtime.bigint() - t0) / 1e6);
-    const output = child.stdout ?? "";
-    const passed = child.status === 0;
+      if (outcome.timedOut) {
+        result.passed = false;
+        result.timedOut = true;
+        result.output = `${outcome.output}\n\n${timeoutAdvice(rule, config, timeoutMs)}`;
+        console.log(`TIMED OUT (${(durationMs / 1000).toFixed(1)}s)`);
+      } else {
+        console.log(`${result.passed ? "passed" : "FAILED"} (${(durationMs / 1000).toFixed(1)}s)`);
+      }
+      results.push(result);
+      journal("running");
+    }
+  } finally {
+    for (const signal of SIGNALS) process.off(signal, onSignal);
+  }
 
-    console.log(`${passed ? "passed" : "FAILED"} (${(durationMs / 1000).toFixed(1)}s)`);
-    results.push({ rule, passed, todo: false, durationMs, output });
+  if (stopped) {
+    journal("killed");
+    console.error(`\nhighball: stopped by ${stopped} — run journaled as killed`);
+    return 1;
   }
 
   // Stamped pass or fail: after a failure the agent's next reads must not
@@ -146,59 +220,18 @@ export async function run(args) {
 
   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 { host, key } = resolvePosthog(config);
   if (host && key) {
     await reportPosthog({
       host, key, project: config.project, results, hook, fastOnly, startedAt,
-      durationMs, branch, commitSha, version: VERSION
+      durationMs, branch: context.branch, commitSha: context.commit, version: VERSION
     });
   }
 
   // The local journal is unconditional — `highball runs` works with no
-  // reporting configured at all. Journal failures never fail the checks,
-  // same policy as reporting.
-  try {
-    appendRun(config.project, {
-      started_at: startedAt.toISOString(),
-      // The repo this run happened in — how the MCP server later resolves
-      // "the current project" and grounds the widget's re-run buttons.
-      dir: process.cwd(),
-      // Which agent session, and what it was working on — the grouping
-      // key and label for run history views. The hook payload points at
-      // the session transcript; its last real user prompt is the work.
-      session: hook.session_id || null,
-      work: latestUserPrompt(hook.transcript_path),
-      duration_ms: durationMs,
-      trigger: fastOnly ? "edit" : "stop",
-      branch,
-      commit: commitSha,
-      status: failures.length === 0 ? "passed" : "failed",
-      results: results.map((result) => ({
-        id: result.rule.id,
-        name: result.rule.name,
-        status: result.todo ? "todo" : result.passed ? "passed" : "failed",
-        duration_ms: result.durationMs,
-        // The command that produced this result. Quiet rules journal no
-        // output at all (the AI judges print nothing when they pass), which
-        // left viewers with an expandable row wrapping an empty panel; the
-        // command is the one detail every real rule can always show. todo
-        // rules have no command — nothing ran — which is exactly what makes
-        // them inert rather than falsely clickable.
-        command:
-          result.rule.run ??
-          (result.rule.rubric ? `judge ${result.rule.rubric}` : null),
-        // Unlike PostHog (one-line summaries only), the journal keeps
-        // every rule's output GitHub-Actions-style — it's the user's own
-        // disk, and `highball runs <n> --logs` is the payoff.
-        output_tail: result.output ? result.output.slice(-10_000) : null
-      }))
-    });
-  } catch (error) {
-    console.error(`highball journal skipped: ${error.message}`);
-  }
+  // reporting configured at all.
+  journal(failures.length === 0 ? "passed" : "failed");
 
   if (failures.length === 0) return 0;
 
@@ -211,6 +244,131 @@ export async function run(args) {
   return 2;
 }
 
+// The journal's view of a run at some moment: the same shape whether the
+// run is still going, finished, or was stopped, so every reader handles
+// one record type and `status` alone says which.
+function journalRecord(context, status, results) {
+  return {
+    id: context.id,
+    started_at: context.startedAt.toISOString(),
+    // The repo this run happened in — how the MCP server later resolves
+    // "the current project" and grounds the widget's re-run buttons.
+    dir: process.cwd(),
+    // Which agent session, and what it was working on — the grouping
+    // key and label for run history views. The hook payload points at
+    // the session transcript; its last real user prompt is the work.
+    session: context.session,
+    work: context.work,
+    duration_ms: Date.now() - context.startedAt.getTime(),
+    trigger: context.fastOnly ? "edit" : "stop",
+    branch: context.branch,
+    commit: context.commit,
+    status,
+    results: results.map((result) => ({
+      id: result.rule.id,
+      name: result.rule.name,
+      status: result.todo ? "todo" : result.passed ? "passed" : "failed",
+      duration_ms: result.durationMs,
+      // Why a failed rule failed, when the reason was the runner's and not
+      // the rule's. Absent otherwise, so ordinary records stay as they were.
+      ...(result.timedOut ? { timed_out: true } : {}),
+      ...(result.killed ? { killed: true } : {}),
+      // The command that produced this result. Quiet rules journal no
+      // output at all (the AI judges print nothing when they pass), which
+      // left viewers with an expandable row wrapping an empty panel; the
+      // command is the one detail every real rule can always show. todo
+      // rules have no command — nothing ran — which is exactly what makes
+      // them inert rather than falsely clickable.
+      command:
+        result.rule.run ??
+        (result.rule.rubric ? `judge ${result.rule.rubric}` : null),
+      // Unlike PostHog (one-line summaries only), the journal keeps
+      // every rule's output GitHub-Actions-style — it's the user's own
+      // disk, and `highball runs <n> --logs` is the payoff.
+      output_tail: result.output ? result.output.slice(-10_000) : null
+    }))
+  };
+}
+
+// What the agent reads after a rule ran out of time. It names the knob,
+// because the right fix is sometimes a slower rule's honest budget and
+// sometimes a hang — and either way the number should be a decision
+// someone made in checks.yml, not a mystery.
+function timeoutAdvice(rule, config, timeoutMs) {
+  const seconds = timeoutMs / 1000;
+  const knob = rule.timeout != null
+    ? `\`timeout: ${seconds}\` on this rule`
+    : `\`timeouts.${rule.rubric ? "judge" : rule.fast ? "fast" : "full"}: ${seconds}\``;
+  return `highball: timed out after ${seconds}s and was killed. Its budget is ${knob} ` +
+    `in ${CONFIG_PATH} — raise it there if this rule legitimately needs longer, ` +
+    "or find what hung.";
+}
+
+// Output kept per rule. Past this the rest is dropped rather than buffered:
+// a runaway logger must not turn into a runaway runner.
+const MAX_OUTPUT = 32 * 1024 * 1024;
+
+// Runs one rule's command with a wall-clock budget. Resolves rather than
+// rejects in every case — a rule that can't even start is a failed rule
+// with the error as its output, not a crashed runner.
+function runCommand(command, { env, timeoutMs, onSpawn }) {
+  return new Promise((resolve) => {
+    const child = spawn(`${command} 2>&1`, {
+      shell: true,
+      // Its own process group (POSIX), so a timeout can kill the rule's
+      // whole tree — the shell, the npm it started, the test runner npm
+      // started — and not just the shell, which would leave a hung suite
+      // running on after the run had already given up on it.
+      detached: process.platform !== "win32",
+      env,
+      stdio: [ "ignore", "pipe", "pipe" ]
+    });
+    onSpawn?.(child);
+
+    let output = "";
+    const collect = (chunk) => {
+      if (output.length < MAX_OUTPUT) output += chunk;
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", collect);
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", collect);
+
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+    }, timeoutMs);
+
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ status: null, output: `${output}${error.message}\n`, timedOut });
+    });
+    child.on("close", (status) => {
+      clearTimeout(timer);
+      resolve({ status, output, timedOut });
+    });
+  });
+}
+
+// Stops a rule's whole process tree: SIGTERM to the group first so
+// anything listening can clean up, SIGKILL a moment later for whatever
+// didn't. Exported for tests.
+export function killTree(child) {
+  const signal = (name) => {
+    try {
+      if (process.platform === "win32" || !child.pid) child.kill(name);
+      else process.kill(-child.pid, name);
+    } catch {
+      // already gone
+    }
+  };
+  signal("SIGTERM");
+  const escalate = setTimeout(() => signal("SIGKILL"), 1000);
+  escalate.unref();
+  child.once("close", () => clearTimeout(escalate));
+}
+
 // Claude Code hooks pass a JSON payload on stdin (session_id and
 // friends); that id groups this run with the rest of the agent's session
 // in the journal and in PostHog. A TTY means a human at a terminal — don't block on

package/lib/runs.js

@@ -15,6 +15,20 @@ const green = (text) => paint("32", text);
 const red = (text) => paint("31;1", text);
 const dim = (text) => paint("2", text);
 
+// A run's status, as a label. "running" is a run the journal has seen
+// start and not finish — live, or one that died without saying so.
+const runLabel = (status) =>
+  status === "passed" ? green("✓ passed")
+    : status === "running" ? dim("… running")
+      : status === "killed" ? red("✗ KILLED")
+        : red("✗ FAILED");
+
+// A rule's status, as a label: a failure the runner caused says why.
+const ruleLabel = (result) =>
+  result.status === "passed" ? green(result.status)
+    : result.status === "todo" ? dim(result.status)
+      : red(result.timed_out ? "TIMED OUT" : result.killed ? "KILLED" : result.status.toUpperCase());
+
 // Column math must use what the eye sees, not what the terminal parses.
 const visible = (text) => text.replace(/\x1b\[[0-9;]*m/g, "");
 const padEnd = (text, width) => text + " ".repeat(Math.max(0, width - visible(text).length));
@@ -70,7 +84,7 @@ function list(project, history) {
     run.trigger === "edit" ? "fast" : "full",
     run.branch || "-",
     dim(run.duration_ms != null ? `${(run.duration_ms / 1000).toFixed(1)}s` : "-"),
-    run.status === "passed" ? green("✓ passed") : red("✗ FAILED"),
+    runLabel(run.status),
     tally(run.results)
   ]);
   const lines = formatRows(rows, new Set([ 4, 5, 6 ]));
@@ -98,7 +112,7 @@ function detail(project, history, number, showLogs) {
   }
 
   const took = run.duration_ms != null ? ` · took ${(run.duration_ms / 1000).toFixed(1)}s` : "";
-  const status = run.status === "passed" ? green("passed") : red("FAILED");
+  const status = runLabel(run.status);
   console.log(
     `Run #${number} — ${project} · ${run.trigger === "edit" ? "fast checks" : "full suite"}` +
       ` · ${run.branch || "-"} · ${(run.commit || "").slice(0, 7)}` +
@@ -112,7 +126,7 @@ function detail(project, history, number, showLogs) {
   const rows = run.results.map((result) => [
     result.status === "passed" ? green("✓") : result.status === "todo" ? dim("•") : red("✗"),
     result.status === "failed" ? red(result.name) : result.name,
-    result.status === "passed" ? green(result.status) : result.status === "todo" ? dim(result.status) : red(result.status.toUpperCase()),
+    ruleLabel(result),
     result.duration_ms != null ? dim(`${(result.duration_ms / 1000).toFixed(1)}s`) : ""
   ]);
   const lines = formatRows(rows, new Set([ 2, 3 ]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/highball",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -14,7 +14,7 @@
     "type": "git",
     "url": "git+https://github.com/profoundry-us/highball.git"
   },
-  "homepage": "https://github.com/profoundry-us/highball#readme",
+  "homepage": "https://highball.profoundry.us",
   "bugs": {
     "url": "https://github.com/profoundry-us/highball/issues"
   },
@@ -27,7 +27,8 @@
     "lib",
     "assets",
     "README.md",
-    "ONBOARDING.md"
+    "ONBOARDING.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"