@stacknyu/pi-check 0.0.0-stage → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# pi-check changelog
+
+## 1.1.1
+
+- Run command helpers asynchronously so native Pi and Pi Web remain responsive; report failed, killed or truncated command results as warnings.
+- Skip invisible status polling in print/JSON mode while retaining native/RPC status support and session-local shutdown behavior.
+- Add isolated command and lifecycle compatibility regressions.
+
+## 1.1.0
+
+- First standalone public npm package, `@stacknyu/pi-check`, maintained in the Stack Pi Plugins monorepo. pi-flow is not installed as a dependency.
+- Includes shared-result revalidation, cancellation fixes, staggered CPU allocation and Go execution/input correctness from the collection's v0.2.0 release.
+- Ships its own Pi extension, skill, CLI, release notes and runtime files; supports independent Pi-managed updates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stacknyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# pi-check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One check runner per repo, shared by every Pi session and every worktree. It handles tests, type checks and linters for **Go, TypeScript/JavaScript and Python**:
+
+- **Only what changed.** A check is split into small units: a Go package, a test file, a project's typecheck, a file's lint. Each unit knows which files it depends on, through the import graph. An agent's check runs only the units its changes touch.
+- **Same files, one run.** Each unit is keyed by the content of everything it depends on. If five worktrees ask for the same unit with the same files, it runs once and all five get the result. A unit already running is joined, not repeated.
+- **Ahead of time.** The broker watches every checkout. When files change, the affected units run at low priority, so results are often ready before the agent asks. These runs never take the last free slot, and they stop when the machine is busy, when an agent's request needs the slot, or when their files change again.
+- **Pre-existing failures are separated.** Failures that also fail on the base branch are reported as pre-existing and don't fail the check. Agents fix what they broke, not old debt.
+- **Short checks have reserved capacity.** One broker/cache, with fast and heavy scheduling lanes—not independent unlimited queues per language. Fast checks cannot be trapped behind long Go suites, and heavy work retains its own slots. With three job slots, two heavy jobs and one fast job can coexist.
+- **Useful throughput, not a utilization ceiling.** Agent count is independent of check concurrency. A shared CPU budget is divided among runnable jobs; Go runs one package per job, rather than multiplying package and runtime parallelism. For tests sharing ports/databases, set the project's `parallel: 1`.
+
+## Install
+
+```bash
+pi install npm:@stacknyu/pi-check   # then reload Pi / Pi Web
+```
+
+This installs only pi-check; pi-flow is not required. Update only this plugin with `pi update npm:@stacknyu/pi-check`, or remove it with `pi remove npm:@stacknyu/pi-check`. See the [repository README](https://github.com/stacknyu/stack-pi-plugins#readme) for publication status, migration, local development and release procedures. The first check starts the broker. It runs in the background and stops after 3 idle hours.
+
+## Use
+
+**Agents** use the `check` tool. They also get a prompt rule that asks them to use it instead of running `go test`, `pytest` or `vitest` in bash. If they run those anyway:
+- `go test` / `go vet`, including inside `make`, go through a `go` shim to the broker, per package, with Go's normal output.
+- Other test, typecheck and lint commands (`pnpm test`, `npx tsc --noEmit`, `pytest`, `ruff`…) run through the broker as a whole command. That run is shared and cached for identical files, and throttled.
+- Commands that change files (`--fix`, `-u`, `install`, `--watch`) always run normally.
+
+**You:**
+
+| | |
+|---|---|
+| `/check` | status: what runs, what waits, time saved |
+| `/check run [all]` | run what your changes affect, or everything |
+| `/check baseline` | run everything on the main checkout (records pre-existing failures) |
+| `/check known [clear\|remove <text>]` | the pre-existing failure list |
+| `/check speculate [all]` | queue affected (or all) units ahead of time |
+| `/check cancel` | drop queued ahead-of-time work for this checkout |
+| `/check init` | write `pi-check.json` with what was detected |
+| `/check reload` | apply configuration once requested work drains; never restart active checks |
+| `/check projects` / `log` / `stop` / `restart` | |
+
+The same commands are on the command line: `node /path/to/pi-check/cli.mjs run`, `status`, `exec -- <cmd>`, and so on (`--json` for scripts).
+
+## What it detects
+
+| Language | Units | Tools |
+|---|---|---|
+| Go | per package: `vet`, `test` | `go vet`, `go test -json`. Inputs: package files, `testdata/`, `//go:embed` files, every in-repo package it and its tests import, `go.mod`/`go.sum` |
+| TypeScript / JS | `typecheck` per package, `lint` per file, `test` per test file | `tsc`/`vue-tsc` (incremental), `eslint`/`oxlint`, `vitest`/`jest`. Inputs: static import graph incl. tsconfig `paths` and workspace packages, configs, setup files, lockfile |
+| Python | `test` per test file, `lint` per file, `typecheck` per project | `pytest` (project `.venv` first, then `uv`/`poetry`, then PATH), `ruff`, `mypy`/`pyright` when configured. Inputs: import closure, `conftest.py` chain, configs |
+| Custom | one unit | any command, with the input globs you give it |
+
+Projects are found by `go.mod`, `package.json` (+ `tsconfig.json` / vitest / jest / eslint / oxlint), and `pyproject.toml` / `setup.cfg` / `pytest.ini`.
+
+## Settings: `pi-check.json` at the repo root (commit it; `.pi-check/config.json` overrides locally)
+
+```json
+{
+  "maxJobs": 0,
+  "speculate": true,
+  "intercept": "route",
+  "ignore": ["**/generated/**"],
+  "projects": {
+    "apps/pocketbase": {
+      "test": { "timeout": "30m", "env": { "PB_SQL_LOG": "0" }, "inputs": ["migrations/**", "pb_schema.json"] },
+      "vet": false
+    },
+    "apps/dashboard": { "lint": { "exclude": ["src/legacy/**"] } }
+  },
+  "custom": [{ "name": "openapi", "cwd": "docs", "cmd": "node scripts/check-openapi.mjs", "inputs": ["docs/api/**"] }]
+}
+```
+
+| Setting | Default | |
+|---|---|---|
+| `maxJobs` | 0 = CPU budget | maximum jobs across all checkouts |
+| `cpuBudget` | 0 = available cores | total cooperative CPU allocation; independent of agent count |
+| `threads` | 0 = automatic | per-job ceiling when positive; automatic allocation divides spare capacity at dispatch |
+| `fastLane` | true | reserve one job slot and one CPU allocation for short checks; disabled automatically with only one slot/core |
+| `nice` | 10 | process priority of check runs |
+| `speculate`, `warmBase` | true, false | affected-only ahead-of-time work; full baseline warming is opt-in |
+| `speculateMaxLoad` | 0.75 | ahead-of-time work only while load < cores × this |
+| `intercept` | `"route"` | raw check commands in agent bash: `route` through the broker, `block` (use the tool), `off` |
+| `shimGo` | true | `go test`/`go vet` in agent bash go through the shim |
+| `base` | the branch the main checkout is on | what "changed" and "pre-existing" compare against |
+| `strict` | false | count pre-existing failures as failures |
+| `projects.<dir>.<kind>` | | `false` disables. `{ args, env, timeout, parallel, inputs, exclude, cmd, lane }`. `inputs` are extra globs (project-relative) the tests read at run time. |
+| `groups` | | concurrency per group, e.g. `{ "go:apps/pocketbase:test": 2 }` |
+| `custom` | [] | extra checks: `{ name, cwd, cmd, inputs, timeout, env, lane }` |
+| `ignore` | [] | globs that are never inputs (generated files, data dirs written by tests) |
+
+## Fast and heavy lanes
+
+`maxJobs` remains the total limit. With `fastLane: true`, one slot/CPU stays reserved even when no fast check is waiting; a long job cannot borrow it and block a later short request. The remaining slots/CPU serve heavy checks. Use `maxJobs: 3` for two heavy jobs plus one short job; with two slots the split is one plus one. `fastLane: false` retains the original shared scheduler. No running requested job is preempted or resized. Automatic per-job allocation leaves capacity for a second heavy requester even when the first arrives alone, rather than leasing the whole heavy budget.
+
+Native lint, vet, typecheck and TypeScript tests default to fast. Fast test batches are bounded to eight units. Recognizable raw type/lint and Node test commands also use that lane; Go tests, builds and unknown commands default to heavy. These are hints, not promises about duration: move slow integration suites or large typechecks to `projects.<dir>.<kind>.lane: "heavy"`, or set `lane` on a custom check. Use `"fast"` for verified short checks. Group limits, priorities/FIFO within each lane, content-cache keys and cross-worktree joins are preserved. The fast lane has at most one running job, so it cannot consume every heavy slot. Status JSON exposes the scheduler revision and per-lane running/queued counts; progress names each running job's lane. Tool allocations are cooperative, not an OS CPU/memory cap.
+
+Source updates require a fresh broker process; `/check reload` reloads configuration, not JavaScript. Keep active checks on their current process and wait for a natural idle exit before starting the updated broker. Do not restart a busy broker to activate scheduling changes.
+
+## With pi-flow
+
+pi-flow uses pi-check automatically when both are installed. Queue checks go through the broker, and item agents are told about the `check` tool. `"checks": ["pi-check"]` in a task runs exactly what each item affects, with pre-existing failures ignored. See pi-flow's README.
+
+## Good to know
+
+- Configuration changes use `/check reload`, not restart. Active and already queued requested work keeps its original configuration. Allocation changes never kill/restart a running job. These are cooperative tool limits, not an OS CPU cap; arbitrary commands can override them.
+- Whole-command/custom jobs already own a broker allocation. Nested pi-check/Go shims run inside that allocation instead of acquiring a second slot. Prefer the native `check` tool for per-unit sharing; arbitrary shell commands are cached as whole commands, not decomposed.
+- Broker connection errors do not automatically launch duplicate direct checks. Inspect status before retrying. An upgrade refuses to replace a busy broker.
+- Status includes elapsed time, allocation and the latest Go test event. Reused unit-runtime is not wall-clock savings. Quiet tests may produce no events until completion.
+- Producers refresh input structure before caching; requesters revalidate their own checkout after execution and baseline classification. Changed inputs produce a stale failure, not an implicit rerun on different content. Cancelling a tool detaches its request without cancelling other waiters.
+- Go ignores unrelated automatic JavaScript/Python lockfile inputs, but preserves explicit runtime inputs. Native sources, transitive embeds, effective toolchain/environment and timeouts participate in keys. Conditional packages use Go's build eligibility. Identical in-repo Go workspaces can share across worktrees; runtime fixtures outside the dependency graph still need explicit inputs.
+- Benchmarks, profiling and artifact-producing Go fallback commands execute rather than reuse whole-command results. CPU allocations override forwarded `GOMAXPROCS`; arbitrary shell commands can still override cooperative limits themselves. Changed key semantics cause a one-time cold cache.
+- Plugin discovery and shims honor `PI_CODING_AGENT_DIR`, including isolated profiles.
+
+- **Pre-existing** means: the same unit fails on the base branch tip in the main checkout, or in any worktree with identical inputs. `/check baseline` records them all at once. The broker also does this by itself when it starts (`warmBase`).
+- **Tests that read files at run time** outside their package (`../../fixtures`) need those files in `inputs`. Otherwise a change there won't rerun them. Embedded files and `testdata/` are already covered.
+- **Tests that write into the repo** (a data dir that isn't git-ignored) change their own inputs. pi-check notices and stops running them ahead of time. Git-ignore that dir, or add it to `ignore`.
+- **Timeouts are never cached.** A Go test that hits its timeout is reported, with a hint to raise `timeout`, and runs again next time.
+- State lives in `.pi-check/` in the main checkout (kept out of git automatically): `cache/`, `known.json`, `state.json`, `broker.log`.
+- The collection requires Node 22.19+, Pi, git, and the tools your projects already use. macOS and Linux; tested with Pi 1.5.0.

package/cli.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// pi-check command line. Agents normally use the `check` tool; this is for people, scripts, the pi-flow
+// runner, and the `go` shim.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { CLI, SHIM_DIR, call, cleanPath, connect, installShims } from "./lib/client.mjs";
+import { CONFIG_FILE } from "./lib/repo.mjs";
+import { STATE_DIR, VERSION, fmtMs, normRel, repoRoots, shq, tailLines, which } from "./lib/util.mjs";
+
+const HELP = `pi-check ${VERSION} — one shared, cached, speculative check runner per repo (Go, TypeScript, Python)
+
+  pi-check run [changed|all] [options]   run checks; prints a report, exit 1 on new failures
+      --files a,b        only units that depend on these files
+      --kind test,lint   test | typecheck | lint | vet | custom
+      --lang go,ts       go | ts | python | custom
+      --project dir      only this project (repeatable)
+      --base ref         compare with this branch (default: the branch the main checkout is on)
+      --strict           pre-existing (base) failures fail too
+      --refresh          ignore cached results
+      --json             machine-readable report
+  pi-check exec [--cwd dir] -- <command>  run a raw command through the broker (shared + cached + throttled)
+  pi-check status [--json]                what runs, what waits, cache savings
+  pi-check projects                       detected projects and checks
+  pi-check baseline                       run everything on the main checkout; failures there become "known"
+  pi-check known [list|add ID…|remove ID|PATTERN…|clear]
+  pi-check speculate [--all]              pre-run what the current changes affect (--all: everything)
+  pi-check cancel                         drop queued/speculative work for this checkout
+  pi-check init                           write ${CONFIG_FILE} with the detected setup
+  pi-check log [-n 80]                    broker log
+  pi-check reload                         apply config after requested work drains
+  pi-check start | stop | restart | forget (clear the cache) | install-shims
+`;
+
+function parse(argv) {
+	const o = { _: [], project: [] };
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--") {
+			o.rest = argv.slice(i + 1);
+			break;
+		}
+		if (a.startsWith("--")) {
+			const [k, v] = a.slice(2).split("=");
+			const bool = ["strict", "refresh", "json", "all", "quiet", "help"].includes(k);
+			const val = bool ? true : (v ?? argv[++i]);
+			if (k === "project") o.project.push(val);
+			else o[k] = val;
+		} else if (a === "-n") o.n = Number(argv[++i]);
+		else o._.push(a);
+	}
+	return o;
+}
+
+const list = (v) => (v ? String(v).split(",").map((s) => s.trim()).filter(Boolean) : undefined);
+const err = (s) => process.stderr.write(`${s}\n`);
+
+async function main() {
+	const argv = process.argv.slice(2);
+	const cmd = argv[0];
+	if (cmd === "shim") return shim(argv.slice(1));
+	const o = parse(argv.slice(1));
+	const cwd = resolve(o.cwd ?? process.cwd());
+	switch (cmd) {
+		case undefined:
+		case "help":
+		case "--help":
+		case "-h":
+			process.stdout.write(HELP);
+			return 0;
+		case "run": {
+			const scope = o._[0] === "all" ? "all" : o.files ? "files" : "changed";
+			const r = await call(cwd, "/run", { scope, files: list(o.files)?.map((f) => toRepoRel(cwd, f)), kinds: list(o.kind), langs: list(o.lang), projects: o.project.length ? o.project : undefined, base: o.base, strict: o.strict, refresh: o.refresh, priority: o.priority ? Number(o.priority) : undefined, label: o.label ?? "cli" }, o.json || o.quiet ? undefined : progress);
+			if (o.json) process.stdout.write(`${JSON.stringify(r.report, null, 2)}\n`);
+			else process.stdout.write(`${r.report.text}\n`);
+			return r.report.ok ? 0 : 1;
+		}
+		case "exec": {
+			const command = (o.rest ?? o._).join(" ");
+			if (!command) return err("usage: pi-check exec [--cwd dir] -- <command>"), 2;
+			return execCommand(cwd, command);
+		}
+		case "status": {
+			const c = await connect(cwd, { start: false });
+			if (!c.info) {
+				process.stdout.write("pi-check broker is not running in this repo (it starts on the first check).\n");
+				return 0;
+			}
+			const s = await call(cwd, "/status");
+			if (o.json) process.stdout.write(`${JSON.stringify(s, null, 2)}\n`);
+			else process.stdout.write(`${statusText(s)}\n`);
+			return 0;
+		}
+		case "projects": {
+			const r = await call(cwd, "/projects", {});
+			for (const p of r.projects) process.stdout.write(`${p.lang.padEnd(7)} ${p.dir.padEnd(32)} ${Object.entries(p.units).map(([k, n]) => `${k}:${n}`).join("  ")}${p.meta?.tester ? `  [${p.meta.tester}]` : ""}${p.meta?.linter ? `  [${p.meta.linter}]` : ""}\n`);
+			if (!r.projects.length) process.stdout.write("No Go modules, TypeScript/JavaScript packages or Python projects with checks found.\n");
+			return 0;
+		}
+		case "baseline": {
+			const rr = repoRoots(cwd);
+			const r = await call(rr.main, "/run", { scope: "all", priority: 5, label: "baseline" }, progress);
+			const k = await call(rr.main, "/known", {});
+			process.stdout.write(`${r.report.text}\n\nKnown failures recorded from the main checkout: ${Object.keys(k.known).length}\n`);
+			return 0;
+		}
+		case "known": {
+			const sub = o._[0] ?? "list";
+			const ids = o._.slice(1);
+			const body = sub === "add" ? { action: "add", ids } : sub === "remove" ? { action: "remove", ids, pattern: ids.length === 1 ? ids[0] : undefined } : sub === "clear" ? { action: "clear" } : {};
+			const r = await call(cwd, "/known", body);
+			const entries = Object.entries(r.known);
+			if (o.json) process.stdout.write(`${JSON.stringify(r.known, null, 2)}\n`);
+			else {
+				for (const [id, k] of entries) process.stdout.write(`${k.source === "manual" ? "[manual] " : ""}${k.title ?? id}\n`);
+				process.stdout.write(`${entries.length} known failure${entries.length === 1 ? "" : "s"}\n`);
+			}
+			return 0;
+		}
+		case "speculate": {
+			const r = await call(cwd, "/speculate", { all: !!o.all });
+			process.stdout.write(`queued ${r.queued} unit${r.queued === 1 ? "" : "s"} at low priority\n`);
+			return 0;
+		}
+		case "cancel": {
+			const rr = repoRoots(cwd);
+			const r = await call(cwd, "/cancel", { root: o.all ? undefined : rr.root });
+			process.stdout.write(`cancelled ${r.cancelled}\n`);
+			return 0;
+		}
+		case "reload": {
+			const r = await call(cwd, "/reload", {});
+			process.stdout.write(r.deferred ? "configuration queued; applies after requested checks finish\n" : "configuration applied\n");
+			return 0;
+		}
+		case "start":
+			await connect(cwd);
+			process.stdout.write("pi-check broker running\n");
+			return 0;
+		case "stop":
+		case "restart": {
+			const c = await connect(cwd, { start: false });
+			if (c.info) {
+				try {
+					await call(cwd, "/stop", {}, undefined, { start: false, timeoutMs: 3000 });
+				} catch {}
+				await new Promise((r) => setTimeout(r, 600));
+			}
+			if (cmd === "restart") await connect(cwd);
+			process.stdout.write(cmd === "restart" ? "pi-check broker restarted\n" : "pi-check broker stopped\n");
+			return 0;
+		}
+		case "forget":
+			await call(cwd, "/forget", {});
+			process.stdout.write("cache cleared\n");
+			return 0;
+		case "log": {
+			const rr = repoRoots(cwd);
+			const p = join(rr.main, STATE_DIR, "broker.log");
+			process.stdout.write(`${existsSync(p) ? tailLines(readFileSync(p, "utf8"), o.n || 80) : "(no log yet)"}\n`);
+			return 0;
+		}
+		case "init": {
+			const rr = repoRoots(cwd);
+			const p = join(rr.main, CONFIG_FILE);
+			if (existsSync(p)) {
+				process.stdout.write(`${CONFIG_FILE} already exists — edit it, then: pi-check reload\n`);
+				return 0;
+			}
+			const r = await call(cwd, "/projects", {});
+			const projects = {};
+			for (const pr of r.projects) projects[pr.dir] = Object.fromEntries(pr.kinds.map((k) => [k, k === "test" ? { timeout: pr.lang === "go" ? "10m" : "15m", env: {} } : {}]));
+			writeFileSync(p, `${JSON.stringify({ $comment: "pi-check settings, shared with the team. Per project: <kind>: false disables it; inputs: extra globs (project-relative) that tests read at runtime; env/args/timeout/parallel per kind.", maxJobs: 0, cpuBudget: 0, threads: 0, speculate: true, warmBase: false, intercept: "route", ignore: [], projects, custom: [] }, null, 2)}\n`);
+			await call(cwd, "/reload", {});
+			process.stdout.write(`wrote ${p}\n`);
+			return 0;
+		}
+		case "install-shims":
+			process.stdout.write(`${installShims()}\n`);
+			return 0;
+		default:
+			process.stdout.write(HELP);
+			return 2;
+	}
+}
+
+function toRepoRel(cwd, f) {
+	const rr = repoRoots(cwd);
+	const abs = resolve(cwd, f);
+	return abs.startsWith(`${rr.root}/`) ? normRel(abs.slice(rr.root.length + 1)) : normRel(f);
+}
+
+let lastProgress = 0;
+function progress(ev) {
+	if (ev.type === "start") err(`pi-check: ${ev.units} units — ${ev.cached} cached, ${ev.joined} already running elsewhere, ${ev.queued} to run`);
+	else if (ev.type === "progress" && Date.now() - lastProgress > 15000) {
+		lastProgress = Date.now();
+		err(`pi-check: ${ev.done ?? "…"}/${ev.total ?? "…"} done · ${ev.text ?? ""}`);
+	}
+}
+
+function statusText(s) {
+	const st = s.stats;
+	const lines = [
+		`pi-check ${s.version} · pid ${s.pid} · up ${s.uptime} · ${s.cpus} cores, load ${s.load} · ${s.maxJobs} job slots, ${s.allocatedCpus ?? "?"}/${s.cpuBudget ?? s.cpus} CPU budget allocated${s.configPending ? " · config waiting for idle" : ""} · speculation ${s.speculate ? "on" : "off"}`,
+		`running (${s.running.length}): ${s.running.map((j) => `${j.root}: ${j.label}${j.speculative ? " [speculative]" : ""} ${j.for}`).join(" | ") || "nothing"}`,
+		`queued: ${s.pending.requested} requested, ${s.pending.speculative} speculative`,
+		`checkouts: ${s.roots.map((r) => `${r.name}${r.watching ? " (watching)" : ""}`).join(", ")}`,
+		`units asked ${st.unitsAsked}: ${st.cacheHits} cached, ${st.joined} joined a run in progress, ${st.ran} ran (+${st.speculativeRan} speculative, ${st.speculativeUsed} of those used) · exec ${st.execRuns} ran / ${st.execHits} reused`,
+		`reused unit-runtime ≈ ${st.saved} (not wall-time savings) · execution time ${st.spent} · preempted ${st.preempted}`,
+		`known (pre-existing) failures: ${s.known}`,
+	];
+	if (s.recent?.length) lines.push("recent:", ...s.recent.slice(0, 6).map((r) => `  ${new Date(r.at).toLocaleTimeString()} ${r.root} ${r.scope} ${r.units}u ${r.ok ? "PASS" : `FAIL(${r.newFailures})`} ${fmtMs(r.ms)} ${r.label}`));
+	return lines.join("\n");
+}
+
+async function execCommand(cwd, command, env) {
+	if (process.env.PI_CHECK_BYPASS === "1") {
+		const r = spawnSync("/bin/sh", ["-c", command], { cwd, stdio: "inherit", env: { ...process.env, PATH: cleanPath() } });
+		return r.status ?? 1;
+	}
+	try {
+		const r = await call(cwd, "/exec", { cwd, cmd: command, env }, (ev) => ev.type === "progress" && progress(ev));
+		process.stdout.write(r.output ?? "");
+		if (r.output && !r.output.endsWith("\n")) process.stdout.write("\n");
+		if (r.source !== "ran") process.stdout.write(Date.now() - r.at < 3000 ? `[pi-check] the same command on identical files was already running${r.source === "shared" ? ` in ${r.root}` : ""} — waited for it and reused its result\n` : `[pi-check] same command on identical files already ran${r.source === "shared" ? ` in ${r.root}` : ""} ${fmtMs(Date.now() - r.at)} ago — result reused, not rerun\n`);
+		if (r.stale) process.stdout.write("[pi-check] files changed while this ran; the result may not match the current files\n");
+		return r.stale ? 1 : r.code ?? 1;
+	} catch (e) {
+		err(`[pi-check] broker unavailable (${e.message}); inspect status before retrying. No unbudgeted duplicate was started.`);
+		return 2;
+	}
+}
+
+// ---------- go shim ----------
+
+const GO_VALUE_FLAGS = new Set(["run", "skip", "timeout", "count", "p", "parallel", "tags", "shuffle", "cpu", "vet", "coverpkg", "covermode", "ldflags", "gcflags", "mod", "modfile", "C", "exec", "o", "outputdir", "coverprofile", "cpuprofile", "memprofile", "blockprofile", "mutexprofile", "trace", "bench", "benchtime", "fuzz", "fuzztime", "list"]);
+const GO_PASSTHROUGH = new Set(["bench", "benchtime", "benchmem", "c", "o", "exec", "coverprofile", "cpuprofile", "memprofile", "blockprofile", "mutexprofile", "trace", "fuzz", "fuzztime", "list", "args", "json", "outputdir", "i", "n", "x", "work", "C", "modfile", "toolexec", "test.v"]);
+
+export function parseGoArgs(a) {
+	const flags = [];
+	const pkgs = [];
+	let verbose = false;
+	let pass = false;
+	let refresh = false;
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i];
+		if (x.startsWith("-") && x !== "-") {
+			const body = x.replace(/^--?/, "");
+			const [name, inline] = body.split(/=(.*)/s);
+			if (GO_PASSTHROUGH.has(name) || name.startsWith("test.")) pass = true;
+			let val = inline;
+			const takesValue = GO_VALUE_FLAGS.has(name) && inline === undefined;
+			if (takesValue) val = a[++i];
+			if (name === "v") {
+				verbose = val !== "false";
+				continue;
+			}
+			if (name === "p") continue; // the broker owns build concurrency
+			if (name === "count") refresh = true;
+			const f = val === undefined ? `-${name}` : `-${name}=${val}`;
+			flags.push(f);
+
+		} else {
+			if (x.endsWith(".go")) pass = true;
+			pkgs.push(x);
+		}
+	}
+	return { flags, pkgs, verbose, pass, refresh };
+}
+
+async function shim(args) {
+	const tool = args[0], rest = args.slice(1);
+	const real = which(tool, { skipDir: process.env.PI_CHECK_SHIM_DIR || SHIM_DIR }) ?? tool;
+	const passthrough = () => {
+		const r = spawnSync(real, rest, { stdio: "inherit", env: { ...process.env, PATH: cleanPath() } });
+		process.exit(r.status ?? 1);
+	};
+	if (tool !== "go" || process.env.PI_CHECK_BYPASS === "1" || !["test", "vet"].includes(rest[0])) return passthrough();
+	const sub = rest[0];
+	const { flags, pkgs, verbose, pass, refresh } = parseGoArgs(rest.slice(1));
+	const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => /^(GO[A-Z0-9_]*|CGO_[A-Z0-9_]+|CC|CXX|PKG_CONFIG)$/.test(k)).sort());
+	env.PATH = cleanPath();
+	const cwd = process.cwd();
+	const rr = repoRoots(cwd);
+	if (!rr) return passthrough();
+	const viaExec = async () => process.exit(await execCommand(cwd, ["go", ...rest].map((s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : shq(s))).join(" "), env));
+	if (pass) return viaExec();
+	const cwdRel = cwd === rr.root ? "." : normRel(cwd.slice(rr.root.length + 1));
+	let r;
+	try {
+		r = await call(cwd, "/run", { goSelect: { cwdRel, patterns: pkgs }, kinds: [sub], extraArgs: flags, extraKey: JSON.stringify(flags), env, refresh, detail: true, label: `go ${sub} (agent)` }, (ev) => ev.type === "progress" && progress(ev));
+	} catch (e) {
+		err(`[pi-check] broker unavailable (${e.message}); inspect status before retrying. No unbudgeted duplicate was started.`);
+		process.exit(2);
+	}
+	const rep = r.report;
+	if (rep.go?.unsupported) return viaExec();
+	const byLabel = new Map((rep.results ?? []).map((x) => [x.label, x]));
+	let anyNew = !rep.ok;
+	const knownLines = [];
+	for (const ip of rep.go?.order ?? []) {
+		const x = byLabel.get(ip);
+		if (!x) {
+			if (sub === "test") process.stdout.write(`?   \t${ip}\t[no test files]\n`);
+			continue;
+		}
+		const tag = x.source === "ran" ? "" : `\t(pi-check: ${x.source === "shared" ? `shared from ${x.root}` : "cached"})`;
+		if (sub === "vet") {
+			if (x.status !== "pass") {
+				const known = new Set(x.known ?? []);
+				process.stderr.write(`# ${ip}\n${(x.failures ?? []).map((f) => `${f.title}${known.has(f.id) ? "  [pre-existing on base]" : ""}`).join("\n")}\n`);
+				if ((x.failures ?? []).some((f) => !known.has(f.id))) anyNew = true;
+			}
+			continue;
+		}
+		if (verbose && x.output) {
+			process.stdout.write(x.output.endsWith("\n") ? x.output : `${x.output}\n`);
+			if (tag) process.stdout.write(`${tag.trim()}\n`);
+			if (x.status === "pass") continue;
+		}
+		if (x.status === "pass") {
+			process.stdout.write(`ok  \t${ip}\t${(x.seconds ?? x.ms / 1000 ?? 0).toFixed(3)}s${tag}\n`);
+			continue;
+		}
+		const known = new Set(x.known ?? []);
+		for (const f of x.failures ?? []) {
+			if (!verbose) process.stdout.write(f.output ? (f.output.endsWith("\n") ? f.output : `${f.output}\n`) : `--- FAIL: ${f.title}\n`);
+			if (known.has(f.id)) knownLines.push(f.title);
+			else anyNew = true;
+		}
+		if (!verbose) process.stdout.write(`FAIL\t${ip}\t${(x.seconds ?? 0).toFixed(3)}s${tag}\n`);
+	}
+	if (knownLines.length) process.stdout.write(`[pi-check] ${knownLines.length} failure${knownLines.length > 1 ? "s" : ""} above also fail on the base branch (pre-existing, not caused by these changes):\n${knownLines.map((l) => `  - ${l}`).join("\n")}\n`);
+	if (anyNew) process.stdout.write("FAIL\n");
+	process.exit(anyNew ? 1 : 0);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) main().then(
+	(code) => process.exit(code ?? 0),
+	(e) => {
+		err(`pi-check: ${e?.message ?? e}`);
+		process.exit(2);
+	},
+);
+
+export { CLI };