Scripts

Scripts

Everything in bin/ is on the agent's PATH while the plugin is enabled. The same files are linked at the repository root for use without the plugin. Each script's header comment says why it exists.

Most have a --self-test. The ones that do not are asset-provenance.py, bump-version.sh, check-pinned-values.sh, holdout.sh and interaction-surface.sh.

Gates: exit nonzero on a problem

Script	Usage	Fails when
assert-ran.sh	assert-ran.sh [--min N] <report> ...	A test run executed zero tests, or fewer than --min. Reads vitest or jest JSON, trx, go test -json and JUnit XML by content. An unreadable report fails.
asset-provenance.py	asset-provenance.py <dir> [--strip] [--quiet]	An image carries provenance or identity metadata. --strip removes it without re-encoding.
check-conflict-markers.sh	check-conflict-markers.sh	A tracked or untracked text file holds git conflict markers. Also fails when it examined zero files.
check-deployed-sha.sh	check-deployed-sha.sh <url> <sha> [--field a.b] [--header Name]	The running build does not report the expected commit sha. Retries 20 times, 6 seconds apart.
check-pinned-values.sh	check-pinned-values.sh <file>:<sed-capture> ...	A value pinned in several files differs. An empty capture fails.
check-runtime.sh	check-runtime.sh [dir]	The Node, .NET or Go version a repository declares does not match the binary on PATH.
check-top-level-md.sh	check-top-level-md.sh [base]	A change adds a root Markdown file not on the allowlist, or one named like pr*, body* or notes*.
check-workflow-keys.py	check-workflow-keys.py [--base B | --all | FILE ...]	A GitHub Actions workflow file has duplicate mapping keys.
holdout.sh	holdout.sh --spec <file> [--dry-run]	See Holdout Check. Exit codes 0 to 3.
style-scan	style-scan [--base REF]	An added line has attribution, slop, or a character at or above U+2000. Exit 2 when it cannot run.
why-red.sh	why-red.sh <log-file>	Exit 1 when the log names a known environmental cause: no Docker, a port in use, the inotify limit, wrong architecture, wrong Node, a full disk, DNS. Exit 2 when the log is missing or empty.

Reports: always exit 0

Script	Usage	Prints
agent-hygiene.sh	agent-hygiene.sh [repo-path ...]	What parallel agents left behind: stuck wait loops, orphaned servers, scratchpad collisions, worktrees on merged branches. Never kills or deletes.
interaction-surface.sh	interaction-surface.sh [base-ref], --wip, --symbols	Unchanged files that import a changed file. With --symbols, also callers of exported symbols the diff changed. The base defaults to origin/master.
needs-review.sh	needs-review.sh [base]	One line per review rule the change fires. See Review Rules.

Tools

Script	Usage	Does
bump-version.sh	bump-version.sh <new-version> [package-dir]	Moves a Node package's version in package.json and the two lock file fields that belong to it, by path, not by pattern. Does not touch a changelog or a tag.
lean-stats	lean-stats collect|report|import-reviews|log-review ...	Keeps ~/.lean/lean.db of tokens by model and role, reviews, merged changes and hook fires, and reports from it. See Measuring a Batch.
heavy.sh	heavy.sh <lane> <command> [args...], heavy.sh status <lane>	Runs a heavy command in a shared lane, one command per lane, at the lowest CPU priority. Waits HEAVY_WAIT seconds (default 300), then exits 75 and names the processes holding the lane. status prints free, or busy and the holders (exit 0 free, 1 busy). With HEAVY_STALL it stops a command that shows no test progress and exits 76. Uses flock on Linux and a Python lock helper elsewhere, so it runs on macOS.
pr-blockers.sh	pr-blockers.sh <pr> [-R owner/repo]	Lists every reason a pull request cannot merge in one read-only call. Exit 0 nothing blocking, 1 blockers, 2 a read failed.
retro-signals.sh	retro-signals.sh --since <date> owner/repo ...	One TSV row per merged pull request. See Measuring a Batch.
sync-default.sh	sync-default.sh [--no-restore]	Refuses a dirty tree, merges the default branch, lists conflicts, then runs a locked restore for each lock file present. Never resets, stashes or checks out files.
workflow-cost.py	workflow-cost.py <run-id> [--prs N] [--baseline-per-pr USD]	Cost per change for a workflow run. See Measuring a Batch.

Brain and test queue

Script	Usage	Does
brain	brain add|list|show|close|reopen|resume|stats|export|session|answers|run-add|queue ...	A local list of what went wrong and is not fixed yet, shared by every session on the machine, plus the test queue. One SQLite file, LEAN_BRAIN_DB. Exit 0 on success, 1 with a message on stderr for a bad id or state, 2 for a usage error. See Brain.
brain-mcp	Started by Claude Code from the plugin's mcpServers entry	An MCP server over stdio that runs brain for a session. It does not expose queue next or queue finish. See Brain MCP.
test-phase	test-phase [PLAN] [--cycle C] [--lane L] [--stall S] [--run-dir D] [--project NAME] [--branch B]	Drains the test queue once, in the heavy.sh lane, and files failures in brain as real, flaky or unverified. A second drainer says so and exits 0. Exit 0 when nothing real failed and no job was cancelled, 1 otherwise. See Test Queue.
lean_remote.py	Not run by hand	The code test-phase calls to run a job on an SSH host: config, preflight, copy, command, cleanup. Only --self-test is a command. See Remote Lanes.

Lanes for heavy.sh

A lane is a name. Use one per toolchain, so a .NET build and an npm install can overlap but two builds cannot.

bash heavy.sh dotnet dotnet build MySolution.sln -nodeReuse:false
bash heavy.sh node   npm ci

Given no command it fails. sync-default.sh sends its restores through the lanes node, dotnet, go and cargo.

Locked restores in sync-default.sh

Lock file	Command
package-lock.json	npm ci
pnpm-lock.yaml	pnpm install --frozen-lockfile
yarn.lock	yarn install --immutable (berry) or --frozen-lockfile (classic)
packages.lock.json	dotnet restore --locked-mode
go.sum	go mod verify
Cargo.lock	cargo fetch --locked

Other files

• skills/adversarial-review/log-review.sh appends one review to the review log.
• templates/refresh-stale-prs.yml is a GitHub workflow. When the default branch moves, it updates the branch of every open pull request that is behind and failing. It never merges or retries a job, skips forks and drafts, and leaves a pull request labelled no-self-heal alone.
• examples/needs-review.rules is a starting rules file.

Where a new script goes

A script that works on any repository goes to this repository as a pull request, with its test. One tied to a repository's layout goes to that repository's scripts/. Either way a person merges it.

Three rules for any script:

• It gets a test.
• When it is wrong, fix the script, not the run.
• It stops at the first surprise and says so.