@profoundry-us/highball 0.1.0 → 0.3.1

package/ONBOARDING.md

@@ -14,13 +14,20 @@ yourself.
 
 ## 0. Preconditions
 
-`npx highball --help` must work (Node >= 18, package installed as a dev
+`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.
 
+**Never run bare `npx highball` where the package is NOT installed**: the
+unscoped npm name `highball` belongs to an unrelated package, and npx
+would fetch that instead of this runner. Installed locally, the bare name
+is safe (npx resolves `node_modules/.bin` first — that's why install is
+step 0); for a one-off without installing, use the scoped form,
+`npx @profoundry-us/highball <command>`.
+
 ## 1. Survey the repo before writing anything
 
 Answer these by reading, not assuming:
@@ -29,19 +36,57 @@ Answer these by reading, not assuming:
   repo *already trust* — look at `package.json` scripts, a `justfile` or
   `Makefile`, CI workflows, README instructions. Wire what exists; invent
   no new tooling in the first pass.
-- **Host or container?** If the toolchain runs in Docker (compose files, a
-  devcontainer), find the dev service's name, then verify the repo mount
-  and working directory by running `pwd` and `ls` through
-  `docker compose exec -T <service>`. Rules will run there; you need to
-  know what paths they see.
+- **Host or container?** Settle this before writing a single rule — see the
+  callout immediately below. Getting it wrong makes every rule fail for the
+  same uninteresting reason, and it is the most common way this setup
+  stalls.
 - **What's fast?** Time candidate commands. Only sub-~2s commands belong
   on the per-edit path; test suites belong at turn end; anything needing a
   live server or long setup should not gate turns at all (leave it to the
   repo's existing workflow, or declare it `todo`).
 
+### If the repo's toolchain lives in Docker
+
+Plenty of repos run *everything* through containers — the host may have no
+Ruby, no Python, no database at all. Highball handles this, but only if you
+declare it. **The runner itself always stays on the host** (that's where the
+hooks fire and where the journal lives); only the rule commands move.
+
+Find the dev service and confirm what it actually sees, rather than assuming
+the layout:
+
+```bash
+docker compose ps --services
+docker compose exec -T <service> sh -c 'pwd && ls'
+```
+
+Then declare the wrapper once, and every rule runs through it:
+
+```yaml
+exec:
+  via: docker compose exec -T --workdir /app app
+```
+
+Four traps, each of which has bitten a real onboarding:
+
+1. **`-T` is mandatory.** Hook shells have no TTY; without it commands hang
+   or die with "the input device is not a TTY".
+2. **Set `--workdir`** to wherever the repo is mounted (verify with `pwd`
+   above). Containers frequently start somewhere other than the mount root.
+3. **Self-orchestrating commands must opt out with `exec: host`.** A
+   `just test` / `make test` target that runs its *own* `docker compose
+   exec` would otherwise be double-wrapped into nonsense.
+4. **Host-only tools opt out too.** If a linter or parser exists on the host
+   but not in the image (`node --check` against a JS bundle, say), mark that
+   rule `exec: host`.
+
+A stopped container makes every wrapped rule fail. That's correct behavior —
+unverifiable is not passing — but say so plainly to your human rather than
+quietly dropping the rules.
+
 ## 2. Scaffold
 
-Run `npx highball init`. It never overwrites: an existing
+Run `npx @profoundry-us/highball init`. It never overwrites: an existing
 `.highball/checks.yml` is kept, and if `.claude/settings.json` already
 exists it prints the hook snippet for you to merge by hand — merge it
 without disturbing existing hooks. Otherwise it creates both files.
@@ -103,7 +148,7 @@ Decision rules:
 You must never see, type, or store a token value. Ask your human to:
 
 1. Create this project (and a token for it) in their Highball app.
-2. Run `npx highball login` themselves — interactively, or piping the
+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,
@@ -112,8 +157,8 @@ vars instead. The repo tree never contains a secret.
 
 ## 5. Verify — all four proofs, not just the happy path
 
-1. **Fast path:** `npx highball run --fast` exits 0, every rule passed.
-2. **Full path:** `npx highball run` exits 0 (or fails honestly on real
+1. **Fast path:** `npx @profoundry-us/highball run --fast` exits 0, every rule passed.
+2. **Full path:** `npx @profoundry-us/highball run` exits 0 (or fails honestly on real
    pre-existing issues — surface those to your human rather than papering
    over them).
 3. **The guardrail:** prove exit 2 works. Create an obviously-temporary

package/README.md

@@ -13,6 +13,11 @@ block, they just aren't recorded.
 
 Published releases: `npm install --save-dev @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
+README, or a one-off — is a single uninstalled checkout away from fetching
+a stranger's code and running it.
+
 From a local tarball (pre-release):
 
 ```bash
@@ -25,7 +30,7 @@ npm install --save-dev ../highball-runner/profoundry-us-highball-<v>.tgz
 Highball is installed *by the AI agent that will be checked by it*. After
 installing the package, tell the repo's Claude Code agent:
 
-> Run `npx highball onboard` and follow the instructions.
+> Run `npx @profoundry-us/highball onboard` and follow the instructions.
 
 [ONBOARDING.md](ONBOARDING.md) (which that command prints) walks the agent
 through surveying the repo's real toolchain, scaffolding, writing rules that
@@ -35,8 +40,8 @@ human, and verifying all four proofs — including that exit 2 actually blocks.
 The pieces, for reference or manual setup:
 
 ```bash
-npx highball init    # scaffolds .highball/checks.yml + Claude Code hooks
-npx highball login   # stores this machine's project token (once per machine)
+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
@@ -80,6 +85,48 @@ 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.
 
+## The MCP dashboard widget
+
+`highball mcp` serves the journal over MCP (stdio) with three tools —
+`list_runs`, `get_run`, `run_checks` — and an
+[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) widget:
+in hosts that render Apps (Claude Desktop and friends), asking about your
+checks produces an interactive inline dashboard — click a run for per-rule
+detail with expandable command output, re-run fast or full checks from a
+button. In hosts without Apps support the same tools answer in plain text,
+per the extension's graceful-degradation rule. Register it with the scoped
+name — hosts spawn the server from an arbitrary directory, so it resolves
+from the registry rather than a local install:
+
+```json
+"highball": { "command": "npx", "args": ["-y", "@profoundry-us/highball", "mcp"] }
+```
+
+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.
+
+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
+else gets the full picture as aligned plain text. Widget development has
+its own harness — `npm run harness`, open http://localhost:3777 — which
+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
+
+Every run also 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.
+
 ## Roadmap
 
 AI-judged rules (`rubric:` — headless Claude applying a markdown rubric to

package/assets/dashboard.html

@@ -0,0 +1,331 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  :root {
+    --bg: #ffffff; --fg: #1a1a2e; --muted: #6b7280; --line: #e5e7eb;
+    --card: #f9fafb; --green: #16a34a; --green-bg: #dcfce7;
+    --red: #dc2626; --red-bg: #fee2e2; --gray-bg: #f3f4f6;
+    --accent: #4f39fa;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #111118; --fg: #e5e7eb; --muted: #9ca3af; --line: #2a2a35;
+      --card: #1a1a24; --green: #4ade80; --green-bg: #14321f;
+      --red: #f87171; --red-bg: #3b1518; --gray-bg: #23232e;
+      --accent: #8f85ff;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 12px; background: var(--bg); color: var(--fg);
+    font: 13px/1.5 -apple-system, "Segoe UI", system-ui, sans-serif;
+  }
+  .head { display: flex; align-items: center; gap: 8px; margin-bottom: 10px; flex-wrap: wrap; }
+  .head h1 { font-size: 14px; margin: 0; }
+  .head .spacer { flex: 1; }
+  button {
+    font: inherit; font-size: 12px; border: 1px solid var(--line); border-radius: 6px;
+    background: var(--card); color: var(--fg); padding: 3px 10px; cursor: pointer;
+  }
+  button:hover { border-color: var(--accent); }
+  button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+  .row {
+    display: flex; align-items: center; gap: 10px; padding: 7px 10px;
+    border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    margin-bottom: 6px; cursor: pointer;
+  }
+  .row:hover { border-color: var(--accent); }
+  .row .when, .row .meta { color: var(--muted); font-size: 12px; }
+  .group {
+    color: var(--muted); font-size: 11.5px; font-style: italic;
+    margin: 12px 2px 6px; white-space: nowrap; overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .group:first-child { margin-top: 2px; }
+  .row .spacer { flex: 1; }
+  .chip {
+    font-size: 11px; font-weight: 600; padding: 1px 8px; border-radius: 999px;
+    white-space: nowrap;
+  }
+  .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); }
+  .mono { font-family: ui-monospace, Menlo, monospace; font-size: 12px; }
+  details.rule {
+    border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    margin-bottom: 6px;
+  }
+  details.rule > summary {
+    display: flex; align-items: center; gap: 10px; padding: 7px 10px;
+    cursor: pointer; list-style: none;
+  }
+  details.rule > summary::-webkit-details-marker { display: none; }
+  /* A rule with nothing to reveal (todo: no command ran) is NOT a details —
+     it must not advertise a chevron or a pointer cursor it can't honor. */
+  .rule.static > .rowline {
+    display: flex; align-items: center; gap: 10px; padding: 7px 10px;
+  }
+  .rule.static {
+    border: 1px solid var(--line); border-radius: 8px; background: var(--card);
+    margin-bottom: 6px;
+  }
+  .panel { border-top: 1px solid var(--line); padding: 4px 12px 10px; }
+  .panel-label {
+    font-size: 10px; text-transform: uppercase; letter-spacing: 0.08em;
+    opacity: 0.55; margin: 8px 0 4px;
+  }
+  .panel-note { font-size: 12px; opacity: 0.6; margin: 8px 0 2px; }
+  details.rule pre {
+    margin: 0; padding: 8px 10px; border-radius: 6px; background: var(--gray-bg);
+    overflow-x: auto; font-size: 11.5px; line-height: 1.45;
+    font-family: ui-monospace, Menlo, monospace; white-space: pre-wrap;
+  }
+  .empty { color: var(--muted); padding: 18px 6px; text-align: center; }
+  .glyph { width: 14px; text-align: center; font-weight: 700; }
+  .glyph.passed { color: var(--green); }
+  .glyph.failed { color: var(--red); }
+  .glyph.todo { color: var(--muted); }
+</style>
+</head>
+<body>
+<div id="app"><div class="empty">Loading Highball runs…</div></div>
+<script>
+(() => {
+  // Minimal MCP Apps client: JSON-RPC 2.0 over postMessage to the host.
+  // Kept dependency-free on purpose — the protocol surface this widget
+  // needs is initialize, tool-result notifications, and tools/call.
+  const pending = new Map();
+  let nextId = 1;
+  const post = (msg) => window.parent.postMessage(msg, "*");
+  const request = (method, params) => new Promise((resolve, reject) => {
+    const id = nextId++;
+    pending.set(id, { resolve, reject });
+    post({ jsonrpc: "2.0", id, method, params });
+  });
+  const notify = (method, params) => post({ jsonrpc: "2.0", method, params });
+
+  window.addEventListener("message", (event) => {
+    const msg = event.data;
+    if (!msg || msg.jsonrpc !== "2.0") return;
+    if (msg.id !== undefined && msg.method === undefined) {
+      const waiter = pending.get(msg.id);
+      if (waiter) {
+        pending.delete(msg.id);
+        msg.error ? waiter.reject(msg.error) : waiter.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method === "ui/notifications/tool-result") {
+      toolInFlight = false;
+      const result = msg.params?.result ?? msg.params ?? {};
+      if (result.structuredContent) render(result.structuredContent);
+      return;
+    }
+    // The host streams tool-input while the originating tool is still
+    // executing (e.g. run_checks taking seconds) — don't let the
+    // impatient self-fetch clobber the view; the result is coming.
+    if (msg.method === "ui/notifications/tool-input" ||
+        msg.method === "ui/notifications/tool-input-partial") {
+      toolInFlight = true;
+      return;
+    }
+    if (msg.id !== undefined) {
+      post({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "not supported" } });
+    }
+  });
+
+  async function callTool(name, args) {
+    const result = await request("tools/call", { name, arguments: args || {} });
+    if (result?.structuredContent) render(result.structuredContent);
+  }
+
+  // --- rendering ---------------------------------------------------------
+
+  const app = document.getElementById("app");
+  let context = { project: null, dir: null };
+  let toolInFlight = false;
+
+  function esc(text) {
+    return String(text ?? "").replace(/[&<>"]/g, (c) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+  }
+  function timeAgo(iso) {
+    const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+    if (s < 60) return "just now";
+    if (s < 3600) return `${Math.round(s / 60)}m ago`;
+    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 tally(results) {
+    const counts = {};
+    for (const r of results) counts[r.status] = (counts[r.status] || 0) + 1;
+    return [
+      counts.passed ? `${counts.passed}✓` : "",
+      counts.failed ? `${counts.failed}✗` : "",
+      counts.todo ? `${counts.todo} todo` : ""
+    ].filter(Boolean).join(" ");
+  }
+  function header(title, buttons) {
+    return `<div class="head"><h1>${title}</h1><span class="spacer"></span>${buttons}</div>`;
+  }
+  function rerunButtons() {
+    if (!context.dir) return "";
+    return `<button data-act="fast">Re-run fast</button>` +
+           `<button data-act="full">Full suite</button>`;
+  }
+
+  function render(sc) {
+    if (sc.runs && sc.project !== undefined) return renderList(sc);
+    if (sc.run) return renderDetail(sc);
+    if (sc.projects) return renderPicker(sc.projects);
+  }
+
+  // Nothing resolved server-side: offer the journaled projects as
+  // buttons instead of a dead end.
+  function renderPicker(projects) {
+    if (projects.length === 0) {
+      app.innerHTML = `<div class="empty">No runs journaled on this machine yet.</div>`;
+      return resize();
+    }
+    app.innerHTML =
+      header("Highball — pick a project", "") +
+      `<div class="empty" style="padding:10px 6px">` +
+      projects.map((slug) => `<button data-project="${esc(slug)}" style="margin:0 4px">${esc(slug)}</button>`).join("") +
+      `</div>`;
+    app.querySelectorAll("[data-project]").forEach((el) =>
+      el.addEventListener("click", () =>
+        callTool("list_runs", { project: el.dataset.project })));
+    resize();
+  }
+
+  function renderList(sc) {
+    context = { project: sc.project, dir: sc.dir ?? context.dir };
+    // Group header whenever the work (or session) changes between
+    // adjacent runs — the list is chronological, so contiguous runs with
+    // the same prompt are one stretch of work.
+    let lastGroup;
+    const rows = sc.runs.map((run) => {
+      const group = `${run.session ?? ""}·${run.work ?? ""}`;
+      const heading = group === lastGroup ? "" :
+        `<div class="group">${run.work ? "&ldquo;" + esc(run.work) + "&rdquo;" : "no session context"}</div>`;
+      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="when">${timeAgo(run.started_at)}</span>
+        <span class="meta">${run.trigger === "edit" ? "fast" : "full"}</span>
+        <span class="mono">${esc(run.branch || "-")}</span>
+        <span class="spacer"></span>
+        <span class="meta">${run.duration_ms != null ? (run.duration_ms / 1000).toFixed(1) + "s" : ""}</span>
+        <span class="meta">${esc(tally(run.results))}</span>
+      </div>`;
+    }).join("");
+    app.innerHTML =
+      header(`Highball · ${esc(sc.project)}`, rerunButtons()) +
+      (rows || `<div class="empty">No runs recorded yet.</div>`);
+    app.querySelectorAll(".row").forEach((el) =>
+      el.addEventListener("click", () =>
+        callTool("get_run", { project: context.project, index: Number(el.dataset.index) })));
+    wireRerun();
+    resize();
+  }
+
+  function renderDetail(sc) {
+    context = { project: sc.project ?? context.project, dir: sc.dir ?? context.dir };
+    const run = sc.run;
+    const rules = run.results.map((result) => {
+      const duration = result.duration_ms != null
+        ? `${(result.duration_ms / 1000).toFixed(1)}s` : "";
+      const row =
+        `<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) +
+        `<span class="meta">${duration}</span>`;
+
+      // What the panel can actually show. Quiet rules (the AI judges print
+      // nothing when they pass) still have their command, so every rule that
+      // really ran stays worth opening.
+      const parts = [];
+      if (result.command) {
+        parts.push(`<div class="panel-label">Command</div><pre>$ ${esc(result.command)}</pre>`);
+      }
+      if (result.output_tail) {
+        parts.push(`<div class="panel-label">Output</div><pre>${esc(result.output_tail)}</pre>`);
+      }
+      // Journal records written before commands were recorded: keep real
+      // rules openable rather than silently turning them inert.
+      if (parts.length === 0 && result.status !== "todo") {
+        parts.push(`<div class="panel-note">No output captured for this rule.</div>`);
+      }
+
+      if (parts.length === 0) {
+        return `<div class="rule static"><div class="rowline">${row}</div></div>`;
+      }
+      return `<details class="rule"${result.status === "failed" ? " open" : ""}>` +
+        `<summary>${row}</summary><div class="panel">${parts.join("")}</div></details>`;
+    }).join("");
+    app.innerHTML =
+      header(
+        `Run #${run.index} · ${esc(context.project)} · ${run.trigger === "edit" ? "fast" : "full"} · ${esc(run.branch || "-")} <span class="meta">${timeAgo(run.started_at)}</span>`,
+        `<button data-act="back">← All runs</button>` + rerunButtons()
+      ) + rules;
+    app.querySelector('[data-act="back"]').addEventListener("click", () =>
+      callTool("list_runs", { project: context.project }));
+    wireRerun();
+    resize();
+  }
+
+  function wireRerun() {
+    app.querySelectorAll("[data-act=fast],[data-act=full]").forEach((el) =>
+      el.addEventListener("click", async () => {
+        el.disabled = true;
+        el.textContent = "Running…";
+        try {
+          await callTool("run_checks", { dir: context.dir, fast: el.dataset.act === "fast" });
+        } finally {
+          callTool("list_runs", { project: context.project });
+        }
+      }));
+  }
+
+  function resize() {
+    notify("ui/notifications/size-changed", {
+      height: Math.min(600, document.documentElement.scrollHeight + 8)
+    });
+  }
+
+  // --- boot --------------------------------------------------------------
+
+  (async () => {
+    try {
+      await request("ui/initialize", {
+        protocolVersion: "2026-01-26",
+        appInfo: { name: "highball-dashboard", version: "0.3.0" },
+        appCapabilities: {}
+      });
+      notify("ui/notifications/initialized");
+    } catch {
+      // Host may predate the handshake shape; the fallback fetch below
+      // still gives us data if tools/call works.
+    }
+    // If the host doesn't push the originating tool result promptly,
+    // fetch the list ourselves — makes the widget self-sufficient. But
+    // never while a tool is executing (tool-input arrived): the widget
+    // may be preloaded seconds before a slow run_checks resolves.
+    const selfFetch = (attempt) => {
+      if (!app.querySelector(".empty") || attempt > 20) return;
+      if (toolInFlight) return setTimeout(() => selfFetch(attempt + 1), 900);
+      callTool("list_runs", {}).catch(() => {});
+    };
+    setTimeout(() => selfFetch(0), 900);
+  })();
+})();
+</script>
+</body>
+</html>

package/bin/highball.js

@@ -7,6 +7,8 @@ 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";
 
 const [command, ...args] = process.argv.slice(2);
 
@@ -24,6 +26,13 @@ Usage:
   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 mcp              Serve run history over MCP (stdio), with an
+                            MCP Apps dashboard widget for hosts that
+                            render them (e.g. Claude Desktop).
 `;
 
 switch (command) {
@@ -39,6 +48,12 @@ switch (command) {
   case "onboard":
     process.exit(await onboard(args));
     break;
+  case "runs":
+    process.exit(await runs(args));
+    break;
+  case "mcp":
+    await mcp();
+    break;
   default:
     console.log(USAGE);
     process.exit(command === undefined || command === "--help" ? 0 : 1);

package/lib/init.js

@@ -36,17 +36,20 @@ checks:
   #   fast: true
 `;
 
+// 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.
 const HOOKS_JSON = {
   hooks: {
     PostToolUse: [
       {
         matcher: "Write|Edit",
-        hooks: [{ type: "command", command: "npx highball run --fast" }]
+        hooks: [{ type: "command", command: "npx @profoundry-us/highball run --fast" }]
       }
     ],
     Stop: [
       {
-        hooks: [{ type: "command", command: "npx highball run", timeout: 900 }]
+        hooks: [{ type: "command", command: "npx @profoundry-us/highball run", timeout: 900 }]
       }
     ]
   }

package/lib/journal.js

@@ -0,0 +1,58 @@
+// The local run journal: every run appends one JSONL line to
+// ~/.highball/runs/<project>.jsonl, whether or not remote reporting is
+// configured. This is what makes the runner useful with no dashboard at
+// all — `highball runs` reads it — and it lives outside the repo tree
+// (like credentials) so there's no gitignore to manage and no state to
+// leak into commits.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Per-project cap. At ~1-2KB a line this bounds each file around a
+// couple hundred KB — enough history to be useful, never enough to care
+// about.
+const MAX_RUNS = 200;
+
+export function journalDir() {
+  return join(homedir(), ".highball", "runs");
+}
+
+export function journalPath(project, dir = journalDir()) {
+  return join(dir, `${project}.jsonl`);
+}
+
+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));
+  writeFileSync(path, lines.slice(-MAX_RUNS).join("\n") + "\n");
+}
+
+// Newest first — the order every "recent runs" view wants.
+export function readRuns(project, dir = journalDir()) {
+  const path = journalPath(project, dir);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .reverse();
+}
+
+export function journaledProjects(dir = journalDir()) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".jsonl"))
+    .map((name) => name.slice(0, -".jsonl".length))
+    .sort();
+}

package/lib/mcp.js

@@ -0,0 +1,245 @@
+// `highball mcp` — a stdio MCP server over the local run journal, with
+// an MCP Apps dashboard widget. This is the no-install view layer: hosts
+// that support MCP Apps (Claude Desktop et al.) render the widget inline;
+// every tool also returns meaningful text, per the extension's graceful-
+// degradation rule, so plain MCP hosts lose nothing but the pixels.
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  getUiCapability, registerAppResource, registerAppTool, RESOURCE_MIME_TYPE
+} from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { journaledProjects, readRuns } from "./journal.js";
+
+const DASHBOARD_URI = "ui://highball/dashboard.html";
+const BIN_PATH = fileURLToPath(new URL("../bin/highball.js", import.meta.url));
+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) };
+  try {
+    return { project: loadConfig().project, dir: process.cwd() };
+  } 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) };
+  }
+}
+
+// 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;
+}
+
+// List payloads stay lean — output tails ride only on get_run.
+function summarize(run, i) {
+  return {
+    index: i + 1,
+    started_at: run.started_at,
+    duration_ms: run.duration_ms,
+    trigger: run.trigger,
+    branch: run.branch,
+    commit: run.commit,
+    status: run.status,
+    session: run.session ?? null,
+    work: run.work ?? null,
+    reported_run_id: run.reported_run_id,
+    results: (run.results || []).map(({ id, name, status, duration_ms }) =>
+      ({ id, name, status, duration_ms }))
+  };
+}
+
+function reply(text, structuredContent) {
+  return { content: [ { type: "text", text } ], structuredContent };
+}
+
+// --- text rendering ------------------------------------------------------
+// Two audiences: hosts that advertised the MCP Apps UI capability get a
+// short summary (the widget carries the detail), everyone else gets the
+// full picture as aligned plain text — the extension's graceful-
+// degradation rule made concrete. Exported for tests.
+
+const glyphFor = (status) =>
+  status === "passed" ? "✓" : status === "todo" ? "•" : "✗";
+
+export function listText(project, runs) {
+  if (runs.length === 0) return `No runs recorded for ${project} yet.`;
+  const rows = runs.map((run) => [
+    `#${run.index}`,
+    run.status === "passed" ? "✓ passed" : "✗ FAILED",
+    run.trigger === "edit" ? "fast" : "full",
+    run.branch || "-",
+    run.duration_ms != null ? `${(run.duration_ms / 1000).toFixed(1)}s` : "-",
+    run.started_at,
+    run.results.map((result) => glyphFor(result.status)).join("")
+  ]);
+  const widths = rows[0].map((_, col) =>
+    Math.max(...rows.map((row) => row[col].length)));
+  const lines = [ `Runs for ${project} (newest first):` ];
+  let lastGroup;
+  runs.forEach((run, i) => {
+    // Group header whenever the work (or its session) changes between
+    // adjacent runs — the journal is chronological, so contiguous runs
+    // with the same prompt are one stretch of work.
+    const group = `${run.session ?? ""}·${run.work ?? ""}`;
+    if (group !== lastGroup) {
+      lastGroup = group;
+      lines.push(run.work ? `» ${run.work}` : "» (no session context)");
+    }
+    lines.push("  " + rows[i].map((cell, col) => cell.padEnd(widths[col])).join("  "));
+  });
+  return lines.join("\n");
+}
+
+export function detailText(project, index, run) {
+  const took = run.duration_ms != null
+    ? ` · took ${(run.duration_ms / 1000).toFixed(1)}s` : "";
+  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}`;
+    if (result.status === "failed" && result.output_tail) {
+      line += "\n" + result.output_tail.split("\n").map((l) => `      ${l}`).join("\n");
+    }
+    return line;
+  }).join("\n");
+  return `Run #${index} — ${project} · ${run.trigger === "edit" ? "fast checks" : "full suite"}` +
+    ` · ${run.branch || "-"} · ${(run.commit || "").slice(0, 7)} · ${run.status}${took}\n${rules}`;
+}
+
+export async function mcp() {
+  const server = new McpServer({ name: "highball", version: VERSION });
+
+  // Did this client advertise MCP Apps support in its initialize
+  // capabilities (io.modelcontextprotocol/ui)? Checked at call time —
+  // capabilities aren't known yet when tools are registered.
+  const uiHost = () => {
+    const capability = getUiCapability(server.server.getClientCapabilities());
+    return !!capability &&
+      (!capability.mimeTypes || capability.mimeTypes.includes(RESOURCE_MIME_TYPE));
+  };
+
+  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.",
+    inputSchema: {
+      project: z.string().optional()
+        .describe("Project slug; defaults to the current repo's project")
+    },
+    _meta: { ui: { resourceUri: DASHBOARD_URI } }
+  }, async ({ project: explicit }) => {
+    const { project, dir } = resolveProject(explicit);
+    if (!project) {
+      const known = journaledProjects();
+      return reply(
+        `No project resolved. Journaled projects: ${known.join(", ") || "(none)"}`,
+        { projects: known }
+      );
+    }
+    const runs = readRuns(project).map(summarize);
+    return reply(
+      uiHost()
+        ? `${runs.length} runs for ${project} — rendered in the dashboard widget.`
+        : listText(project, runs.slice(0, 20)),
+      { project, dir, runs }
+    );
+  });
+
+  registerAppTool(server, "get_run", {
+    title: "Highball run detail",
+    description:
+      "One Highball run's full detail — per-rule statuses, durations, and " +
+      "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")
+    },
+    _meta: { ui: { resourceUri: DASHBOARD_URI } }
+  }, async ({ index, project: explicit }) => {
+    const { project, dir } = resolveProject(explicit);
+    if (!project) return reply("No project resolved.", {});
+    const history = readRuns(project);
+    const run = history[index - 1];
+    if (!run) return reply(`No run #${index} (${history.length} recorded).`, {});
+    return reply(
+      uiHost()
+        ? `Run #${index} for ${project}: ${run.status} — rendered in the dashboard widget.`
+        : detailText(project, index, run),
+      { project, dir, run: { ...summarize(run, index - 1), results: run.results } }
+    );
+  });
+
+  registerAppTool(server, "run_checks", {
+    title: "Run Highball checks",
+    description:
+      "Execute a repo's Highball checks (fast rules or the full suite). " +
+      "Blocks until done; the run lands in the journal and, when reporting " +
+      "is configured, on the dashboard.",
+    inputSchema: {
+      dir: z.string().optional()
+        .describe("Repo root containing .highball/checks.yml; defaults to cwd"),
+      fast: z.boolean().optional().describe("Only rules marked fast: true")
+    },
+    _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();
+    const child = spawnSync(
+      process.execPath,
+      [ BIN_PATH, "run", ...(fast ? [ "--fast" ] : []) ],
+      { cwd, encoding: "utf8", timeout: 900_000, env: { ...process.env, NO_COLOR: "1" } }
+    );
+    const output = `${child.stdout || ""}${child.stderr || ""}`.slice(-4000);
+    let project = null;
+    let latest = null;
+    try {
+      project = loadConfig(cwd).project;
+      latest = readRuns(project)[0] || null;
+    } catch {
+      // No checks.yml at cwd — the child's own error output says so.
+    }
+    return reply(
+      `exit ${child.status}\n${output}`,
+      {
+        project,
+        dir: cwd,
+        exitCode: child.status,
+        run: latest ? { ...summarize(latest, 0), results: latest.results } : null
+      }
+    );
+  });
+
+  registerAppResource(server, "Highball Dashboard", DASHBOARD_URI, {}, async () => ({
+    contents: [ {
+      uri: DASHBOARD_URI,
+      mimeType: RESOURCE_MIME_TYPE,
+      text: readFileSync(new URL("../assets/dashboard.html", import.meta.url), "utf8")
+    } ]
+  }));
+
+  await server.connect(new StdioServerTransport());
+}

package/lib/report.js

@@ -5,7 +5,9 @@
 import { execSync } from "node:child_process";
 import { hostname } from "node:os";
 
-export async function report({ url, token, rules, results, hook, fastOnly, startedAt }) {
+// 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) => {
@@ -29,8 +31,8 @@ export async function report({ url, token, rules, results, hook, fastOnly, start
       session_key:
         hook.session_id || process.env.HIGHBALL_SESSION_KEY || `manual-${hostname()}`,
       trigger: fastOnly ? "edit" : "stop",
-      branch: git("git branch --show-current"),
-      commit_sha: git("git rev-parse HEAD"),
+      branch,
+      commit_sha: commitSha,
       rules_snapshot: rules,
       started_at: startedAt.toISOString()
     });
@@ -57,12 +59,14 @@ export async function report({ url, token, rules, results, hook, fastOnly, start
       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;
   }
 }
 
-function git(command) {
+export function git(command) {
   try {
     return execSync(`${command} 2>/dev/null`, { encoding: "utf8" }).trim();
   } catch {

package/lib/run.js

@@ -5,7 +5,9 @@
 // dashboard must never block the agent.
 import { execSync, spawnSync } from "node:child_process";
 import { loadConfig, resolveReporting, commandFor } from "./config.js";
-import { report } from "./report.js";
+import { appendRun } from "./journal.js";
+import { git, report } from "./report.js";
+import { latestUserPrompt } from "./transcript.js";
 
 export async function run(args) {
   // When an AI-judged rule spawns a judge session inside this repo, the
@@ -66,10 +68,58 @@ 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 { url, token } = resolveReporting(config);
+  let reportedRunId = null;
   if (url && token) {
-    await report({ url, token, project: config.project, rules, results, hook, fastOnly, startedAt });
+    reportedRunId = await report({
+      url, token, rules, results, hook, fastOnly, startedAt, branch, commitSha
+    });
+  }
+
+  // The local journal is unconditional — `highball runs` works with no
+  // dashboard 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",
+      reported_run_id: reportedRunId,
+      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 ?? null,
+        // Unlike the dashboard (failure tails 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}`);
   }
 
   if (failures.length === 0) return 0;
@@ -105,8 +155,10 @@ async function readHookPayload() {
 // every rule invocation fail; scripts fall back to their own git.
 function changedFiles() {
   try {
-    const tracked = execSync("git diff --name-only HEAD", { encoding: "utf8" });
-    const untracked = execSync("git ls-files --others --exclude-standard", {
+    const tracked = execSync("git diff --name-only HEAD 2>/dev/null", {
+      encoding: "utf8"
+    });
+    const untracked = execSync("git ls-files --others --exclude-standard 2>/dev/null", {
       encoding: "utf8"
     });
     const list = `${tracked}\n${untracked}`

package/lib/runs.js

@@ -0,0 +1,156 @@
+// `highball runs [n] [--logs]` — the no-dashboard view of run history,
+// read from the local journal. Bare: a table of recent runs, newest
+// first. With a number: that run's detail — failure output by default,
+// every rule's captured output with --logs.
+import { loadConfig } from "./config.js";
+import { readRuns, journaledProjects } from "./journal.js";
+
+// TTY-gated ANSI (NO_COLOR respected, FORCE_COLOR overrides) — hook
+// shells and pipes get plain text.
+const COLORS_ON = process.env.FORCE_COLOR
+  ? true
+  : Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
+const paint = (code, text) => (COLORS_ON ? `\x1b[${code}m${text}\x1b[0m` : text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31;1", text);
+const dim = (text) => paint("2", text);
+
+// 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));
+const padStart = (text, width) => " ".repeat(Math.max(0, width - visible(text).length)) + text;
+
+export async function runs(args) {
+  let project;
+  try {
+    project = loadConfig().project;
+  } catch {
+    const known = journaledProjects();
+    console.error(
+      "highball: not inside a configured repo (no .highball/checks.yml)."
+    );
+    if (known.length > 0) {
+      console.error(`Projects with local history: ${known.join(", ")}`);
+    }
+    return 1;
+  }
+
+  const history = readRuns(project);
+  if (history.length === 0) {
+    console.log(`No local runs recorded for ${project} yet — run \`highball run\`.`);
+    return 0;
+  }
+
+  const index = args.find((arg) => /^\d+$/.test(arg));
+  return index
+    ? detail(project, history, Number(index), args.includes("--logs"))
+    : list(project, history);
+}
+
+// Shared column formatter: widths from visible lengths, chosen columns
+// right-aligned so numbers and ✓/✗ line up whatever the text does.
+function formatRows(rows, rightAligned) {
+  const widths = rows[0].map((_, col) =>
+    Math.max(...rows.map((row) => visible(row[col]).length))
+  );
+  return rows.map((row) =>
+    "  " + row
+      .map((cell, col) =>
+        rightAligned.has(col) ? padStart(cell, widths[col]) : padEnd(cell, widths[col])
+      )
+      .join("  ")
+  );
+}
+
+function list(project, history) {
+  console.log(`Recent runs for ${project} (newest first):\n`);
+  const rows = history.map((run, i) => [
+    dim(`#${i + 1}`),
+    timeAgo(run.started_at),
+    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"),
+    tally(run.results)
+  ]);
+  const lines = formatRows(rows, new Set([ 4, 5, 6 ]));
+  // Group header whenever the work (or session) changes between adjacent
+  // runs — contiguous runs with the same prompt are one stretch of work.
+  let lastGroup;
+  history.forEach((run, i) => {
+    const group = `${run.session ?? ""}·${run.work ?? ""}`;
+    if (group !== lastGroup) {
+      lastGroup = group;
+      if (i > 0) console.log("");
+      console.log(dim(run.work ? `» ${run.work}` : "» (no session context)"));
+    }
+    console.log(lines[i]);
+  });
+  console.log(`\nDetail: highball runs <number> [--logs]`);
+  return 0;
+}
+
+function detail(project, history, number, showLogs) {
+  const run = history[number - 1];
+  if (!run) {
+    console.error(`highball: no run #${number} (${history.length} recorded).`);
+    return 1;
+  }
+
+  const took = run.duration_ms != null ? ` · took ${(run.duration_ms / 1000).toFixed(1)}s` : "";
+  const status = run.status === "passed" ? green("passed") : red("FAILED");
+  console.log(
+    `Run #${number} — ${project} · ${run.trigger === "edit" ? "fast checks" : "full suite"}` +
+      ` · ${run.branch || "-"} · ${(run.commit || "").slice(0, 7)}` +
+      ` · ${timeAgo(run.started_at)} · ${status}${dim(took)}`
+  );
+  if (run.reported_run_id) console.log(dim(`reported as run ${run.reported_run_id}`));
+  console.log("");
+
+  // Same table treatment as the list view: rule rows aligned in
+  // columns, output blocks interleaved beneath their rule's row.
+  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()),
+    result.duration_ms != null ? dim(`${(result.duration_ms / 1000).toFixed(1)}s`) : ""
+  ]);
+  const lines = formatRows(rows, new Set([ 2, 3 ]));
+  run.results.forEach((result, i) => {
+    console.log(lines[i]);
+    const wantOutput = result.status === "failed" || showLogs;
+    if (wantOutput && result.output_tail) {
+      console.log(indent(result.output_tail));
+    } else if (showLogs && !result.output_tail) {
+      console.log(indent(dim("(no output captured)")));
+    }
+  });
+  if (!showLogs) console.log(dim(`\nAll captured output: highball runs ${number} --logs`));
+  return 0;
+}
+
+function indent(text) {
+  return text
+    .replace(/\n$/, "")
+    .split("\n")
+    .map((line) => `      ${line}`)
+    .join("\n");
+}
+
+function tally(results) {
+  const counts = { passed: 0, failed: 0, todo: 0 };
+  for (const result of results) counts[result.status] = (counts[result.status] || 0) + 1;
+  return [
+    counts.passed ? green(`${counts.passed}✓`) : null,
+    counts.failed ? red(`${counts.failed}✗`) : null,
+    counts.todo ? dim(`${counts.todo} todo`) : null
+  ].filter(Boolean).join(" ");
+}
+
+function timeAgo(iso) {
+  const seconds = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86_400) return `${Math.round(seconds / 3600)}h ago`;
+  return `${Math.round(seconds / 86_400)}d ago`;
+}

package/lib/transcript.js

@@ -0,0 +1,60 @@
+// Extracts "the work being done" from a Claude Code session transcript:
+// the last real user prompt. Hooks hand the runner transcript_path on
+// stdin, and the message that started the current turn is the best
+// zero-cost description of why these checks are running — no AI
+// summarization, no config, just the tail of a JSONL file.
+import { existsSync, readFileSync } from "node:fs";
+
+const MAX_LENGTH = 120;
+
+export function latestUserPrompt(transcriptPath) {
+  if (!transcriptPath || !existsSync(transcriptPath)) return null;
+  let lines;
+  try {
+    lines = readFileSync(transcriptPath, "utf8").split("\n");
+  } catch {
+    return null;
+  }
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    if (entry.type !== "user" || entry.isMeta) continue;
+    const text = messageText(entry.message);
+    if (text) return truncate(text);
+  }
+  return null;
+}
+
+// A "user" line is only a prompt when it carries actual text — tool
+// results and command wrappers ride the user role too and must not
+// become work descriptions.
+function messageText(message) {
+  if (!message) return null;
+  const { content } = message;
+  let text = null;
+  if (typeof content === "string") text = content;
+  else if (Array.isArray(content)) {
+    text = content
+      .filter((item) => item.type === "text" && typeof item.text === "string")
+      .map((item) => item.text)
+      .join(" ");
+  }
+  if (!text) return null;
+  text = text.trim();
+  if (!text || text.startsWith("<")) return null;
+  if (text.startsWith("[Request interrupted")) return null;
+  return text;
+}
+
+function truncate(text) {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > MAX_LENGTH
+    ? collapsed.slice(0, MAX_LENGTH - 1) + "…"
+    : collapsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/highball",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "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.",
   "keywords": [
     "ai",
@@ -25,6 +25,7 @@
   "files": [
     "bin",
     "lib",
+    "assets",
     "README.md",
     "ONBOARDING.md"
   ],
@@ -32,9 +33,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "harness": "node dev/harness/serve.js"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.5.0"
   },
   "license": "MIT"