Repository navigation
Releases
v0.5.2
Fixed
- A remote job's own inputs no longer leak into its command. A heavyq run inside a remote job (a test of heavyq, a nested queue) could read the outer job's base ref and fail with "cannot create base ref"; every input is now set explicitly and unset before the command runs.
PASS?: an exit 0 that says a command was not found no longer passes quietly. A run that exits 0 while its output has a shell not-found line (sh: 1: tsc: not found,bash: line 1: tsc: command not found) usually hides a missing tool behind a pipeline (npx tsc | tail). It now endsPASS?with a warning quoting the line, is recorded assuspect(never as proof, never cached) and still exits 0;--strict, gates and item proofs make it exit 127. Ash -cstring with a pipe draws a one-time warning about the last-stage exit status, and gate commands run underbash -o pipefailwhere bash exists (gate runs recorded before this change are proven again). See docs/exit-codes.md.
Install (checks the sha256 of the archive): curl -fsSL https://github.com/LysCongThanh/heavyq/releases/download/v0.5.2/install.sh | sh
Verify a download (build provenance and a cosign signature, both from GitHub Actions through Sigstore):
gh attestation verify heavyq_0.5.2_linux_amd64.tar.gz --repo LysCongThanh/heavyq
cosign verify-blob --bundle heavyq_0.5.2_linux_amd64.tar.gz.sigstore.json \
--certificate-identity "https://github.com/LysCongThanh/heavyq/.github/workflows/release.yml@refs/tags/v0.5.2" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com heavyq_0.5.2_linux_amd64.tar.gzv0.5.1
Added
--with REPO[@REF], now complete. A command that reads../shared-schemaor../core-libdeclares those sibling repositories; each is pinned to a commit at enqueue (a missing directory, a non-repository, an unknown ref, an unsafe or main-repo name or a repeat exits 2 before anything is queued), pushed and checked out next to the remote worktree, and removed with it. A local run is eligible only when every sibling sits at../<name>on its pinned commit with a clean tree (checked again when the ticket gets a slot); otherwise--remote localexits 2 naming the sibling, andautouses the remotes only. Siblings are part of the run id, so--cacheworks with them and a sibling at another commit is never a cache hit or a proof;status,status --json,history -vand the ledger showwith: name@sha12.../<name>in the command no longer keeps default placement local. See docs/remote.md.--need-gh. For a command that calls the GitHub CLI with your login, which only this machine has: the run stays local, and--remote <name>with it is a usage error.[run] need_gh_repos = ["app"]in the user config makes it implicit for those repositories (one stderr line says why).- Gates carry both. A
[[gate]]may setwith = ["shared-schema@v2.1.0"]andneed_gh = true;heavyq gate runpasses them to every command, andgate statuslooks for runs on the same sibling commits. The JSON schemas are updated.
Fixed
install.sh --verifynames the cosign it needs. Release bundles need cosign 3 or later; cosign 2 failed with a bare "signature is not valid". The installer now says which cosign it found and that verifying needs cosign 3, and docs/install.md shows it with a current version (#142).
Install (checks the sha256 of the archive): curl -fsSL https://github.com/LysCongThanh/heavyq/releases/download/v0.5.1/install.sh | sh
Verify a download (build provenance and a cosign signature, both from GitHub Actions through Sigstore):
gh attestation verify heavyq_0.5.1_linux_amd64.tar.gz --repo LysCongThanh/heavyq
cosign verify-blob --bundle heavyq_0.5.1_linux_amd64.tar.gz.sigstore.json \
--certificate-identity "https://github.com/LysCongThanh/heavyq/.github/workflows/release.yml@refs/tags/v0.5.1" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com heavyq_0.5.1_linux_amd64.tar.gzv0.5.0
Added
-
Signed releases. Every archive and
checksums.txtnow has a cosign keyless signature
(<file>.sigstore.json, made by the release workflow through Sigstore with GitHub OIDC), next to the existing
SPDX SBOMs and GitHub build-provenance attestation. This is what the Scorecard Signed-Releases check reads. The
release footer and docs/install.md showcosign verify-bloband
gh attestation verify. Releases are immutable (repository setting), andv*tags are protected from deletion
and force-push (ruleset). -
install.sh, attached to every release and listed in its signedchecksums.txt: detects OS and CPU,
downloads the archive, checks its SHA-256 againstchecksums.txt(a mismatch or a duplicated line installs
nothing), installs into~/.local/binor--prefix DIR/binatomically, and with--verifyalso checks the
cosign signature.--versionpins a release. Tested in CI on Linux and macOS against a local fake release and
against real releases (docs/install.md). -
heavyq <command> --help(andheavyq help <command>) prints a real usage block: what the command does,
its synopsis, its flags with descriptions, and a link to its docs, instead of the Go flag defaults. It works
without a config and for subcommands (heavyq gate run --help). A--helpafter--still belongs to your
command. -
heavyq completion bash|zsh|fish: shell completion scripts for commands, subcommands, flags and their
values (--remote local|auto,--scope ..., paths); after--they complete the program you queue. They run
on bash 3.2 (macOS) and need no bash-completion package. -
Man page
heavyq(1), generated at release bytools/mangenand shipped in every archive as
man/man1/heavyq.1. The help blocks, completions and man page are generated from one command table
(internal/cli/command_table_*.go); tests fail when it and the code or the usage text disagree. -
JSON Schemas in
schema/forheavyq.toml, the user config andheavyq status --json, generated from the
Go types bytools/schemagen(a separate module, so the main module keeps its single dependency). Add
#:schema https://raw.githubusercontent.com/LysCongThanh/heavyq/main/schema/heavyq.schema.jsonas the first line
of a file for completion, hover help and errors in Taplo-based editors
(docs/configuration.md). CI regenerates them and fails on a
difference. -
Steer: a brief after compaction and a stop gate that wants proof (docs/steer.md,
internal/steer).heavyq brief [--json]: the goal, the asking lane's items, the one next command, a red gate, items that need
a human and one machine-pressure line, in at most 300 tokens (bytes / 4; a test holds the worst case). The
SessionStart hook injects it asadditionalContexton startup, resume and compact, so/compactcannot erase
the thread. Silent in a repository that never used heavyq.heavyq steer off|guard|destroy, stored per repository in the git common dir (defaultoff;
HEAVYQ_STEERoverrides it,offis the kill switch). The Stop hook blocks while the lane holds claimed
items that are not proven on this tree, and every block names the exact next command
(heavyq item done <id> --run) and an escape (item block ... "needs: ...",item release).guardblocks
at most 3 times per session and honoursstop_hook_active(no second block on an unchanged situation); items
that are blocked, released, without a proof, or whose proof was already red when the session started
(a baseline recorded at SessionStart) never block.destroyhas no cap, also gates SubagentStop,
TaskCompleted and TeammateIdle (exit 2 with the reason on stderr) and repeats the brief in every block;
heavyq steer destroyprints how to lift Claude Code's native cap (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=0) and
--applywrites it to the Claude Code settingsenvblock (a.bakis kept, idempotent).- Claim vs ledger: when the last assistant message says the tests pass (two conservative phrases) and the
ledger shows a plain failure on this tree that was not red at the start, the Stop hook continues once with the
fact, without blocking. - Delivery canary: each brief carries a short random token;
heavyq doctorlooks for it in the transcript
path the hook was given (best effort, never changes the exit code). heavyq hook install claude --features queue,brief,stop(defaultqueue; the exact set, foreign hooks are
kept) and the plugin'shooks.jsonnow carry SessionStart, Stop, SubagentStop, TaskCompleted and
TeammateIdle, behind the samecommand -v heavyqguard. New hooks plug in with one row in the feature table
and the shared hook input/output helpers (internal/hook/claude_hook_io.go). Hook handlers run under
deadline.RunWithinand fail open. Golden tests pin each hook's JSON; table tests cover the stop decisions;
an end-to-end test drives a temporary repository (claim, edit, Stop blocks with the next command, gate run,
Stop allowed).
-
heavyq top: a terminal monitor for the pane next to your agents (docs/top.md). It reads
the same snapshot asstatus --jsonand the dashboard and redraws every 2 s (--interval): what needs you
first (red gates bound to their tree, loops, starved jobs, machines down, blocked items), one row per ticket
with the short reason it waits, machines with a RAM bar marked at what a heavy job needs, pools and the story
sentence. Five display modes,--mode full|focus|lanes|machines|lineormat runtime (the last one is
remembered in$XDG_STATE_HOME/heavyq/top-mode);--line/--onceprint one frame for tmux
status-rightor scripts. Keys:j k g G Tab,Enter(why),/filter,r,?,y(copy, OSC 52),
q; with--control,c(inline y/n),+ -(priority) andp(pause) go through the same control mailbox
and checks as the dashboard. No TUI framework: hand-rolled ANSI, alternate screen restored on exit,
SIGINT/TERM/HUP, Ctrl-Z/SIGCONT and panics, synchronized output, width measured in cells,NO_COLOR, ASCII
fallback, a 60-column floor. The one new dependency isgolang.org/x/term(raw mode and terminal size).
Humans only: thehelp agentscard is unchanged. -
macOS remotes: run heavy jobs on a spare Mac (docs/remote.md).
A stock Mac (noflock, nosetsid, no Homebrew) is now a valid[[remote]]. Where util-linux is missing the
remote script uses Perl, which ships with macOS:flock()for the slot lock (the sameflock(2)on the same
lock files, so busy slots look the same to the probe) andPOSIX::setsid()for the command's process group.
The stdin lifeline teardown is unchanged and was checked against a real Mac for cancel, heavyq dying and a
hard disconnect, with no process left behind. The probe readssysctlandvm_statthrough the same parser
and formulas as the local macOS sampler (metrics.ParseDarwin). Remote commands get the login shell's PATH on
macOS, and the new per-remoteenv_pathkey puts extra directories first (~/is the remote home), for
toolchains the login shell does not set, such as~/.local/go-sdk/bin. Linux remotes behave as before. -
heavyq receipts [--day|--week|--month] [--share] [--json]: a shareable, privacy-rounded summary
(internal/receipts, docs/receipts.md). Counts from the ledger window: heavy runs,
duplicate runs avoided (cache hits plus coalesced), runs held back in the queue, flaky and under-load
failures flagged, remote runs and machines, pool values handed out, wait p50/p95 and agents (lanes) served.
Each metric counts only what the ledger proves; "freezes avoided" is left out because admission records
cannot show it.--sharerounds into ranges ("~40 runs/day", "about 1 in 8 runs"), drops every lane,
repository, command, path and machine name, adds the heavyq version and the window, and prints a compact
box-drawing card of at most 12 lines. The dashboard gets a "Receipts" panel (week/month toggle, "Copy to
share") fed by the new token-protectedGET /api/v1/receipts?window=day|week|month. -
Mentor: break repeat failures, measured with a holdout (
internal/mentor, docs/mentor.md).
The samerun_id(same tree, argv and env) failing again with a deterministic exit code gets one short note,
built from ledger fields only:[heavyq · tool data] <fact>.at the 2nd failure, withNext: <one action>.at
the 3rd. Never for 124, 137, 130, 143 or heavyq's own 75-78 and 255, never forunder_loador flaky runs. It
speaks on a state change only: each level once per signature, 3 events per rule and session, a 3 s cooldown.
heavyq hook claude-posttooluse(for bothPostToolUseandPostToolUseFailure, which is what Claude
Code sends for a failed Bash command) reads the lane's newest records from the ledger index, fails open under
the 15 ms hook budget, and printsadditionalContextonly for the inject arm. Every eligible event is logged
tomentor/interventions.jsonlwith its rule, seed, arm (a seeded 80/20 draw), event and outcome (did the next
heavy run differ, byrun_id, within 3 runs).heavyq mentor stats [--json]shows events, resolved,
differed and rate per rule and arm, and the lift in points;mentor mute|unmute <rule>. A rule under 10 points
of lift after 200 resolved events per arm mutes itself. New[mentor]config (holdout_pct,auto_mute,
min_events,min_lift_pp;holdout_pct = 100is shadow mode),HEAVYQ_MENTOR=off, and
ledgerindex.LaneRuns(a lane's newest records from the index). The settings entry is documented;hook installdoes no...
v0.4.0
Added
- macOS parity: RAM/load gate, CPU attribution, process-tree cancel (no cgo). Local metrics come from
sysctl -n hw.memsize hw.ncpu vm.loadavgandvm_stat(available = free + inactive + purgeable +
speculative pages, capped at installed RAM), soheavyq status --jsonhasmetrics_known: trueon a Mac.
Processes come fromps -axo pid=,ppid=,rss=,time=,comm=(CPU time parsed from[[dd-]hh:]mm:ss[.cc],
executable paths with spaces kept whole), sampled twice for CPU% per lane and for the outside-the-queue
groups. A cancel walks thepsppid map and reaches every grandchild still attached to its parent;
orphans re-parented tolaunchdcan be missed (macOS has no subreaper). Linux keeps/proc, unchanged.
If a command fails, the metrics stay unknown and the gate only enforces slots. CI gains amacosjob. - Stances: thinking modes as files (
internal/stance,heavyq stance ls|show <name> [--json]). A stance
is a short markdown document describing a way of thinking, with TOML frontmatter between+++lines
(name,description,entertriggers,exitconditions,cooldown_minutes,inject_tokens; unknown
keys are errors with the line; body up to 32 KiB, any language). Five built-ins ship embedded:
breakthrough,converge,skeptic,calm,surgeon. Precedence: repo.heavyq/stances/*.mdover
user$XDG_CONFIG_HOME/heavyq/stances(or~/.config/heavyq/stances) over built-in, same name overrides,
and an invalid file is an error, never a silent fallback. A compact renderer produces the injection text,
facts first ([heavyq · stance <name>] why now: ...,next: ..., at most 3 core lines from a
<!-- core -->block,full: heavyq stance show <name>), withininject_tokens(default 150, max 400,
about 4 bytes per token).enter.stallstays parseable but is status-line-only: no built-in enters on
elapsed time alone. This is the pure building block: triggers and injection
come next, nothing changes an agent's behaviour yet. Seedocs/stances.md. - Dashboard Tower: an exception-first home. The top of the page is one calm line (
Nothing needs you. 4 lanes working, 2 unproven.) unless a fact heavyq measured needs a human: a red gate (the latest
conclusive gate run on a lane's current tree failed), a loop (the same command failed twice on the same
tree within 30 minutes), a starved lane (head of the queue past 2/3 offorce_after, or a give-up in
the last hour) or machine trouble (unreachable, paused, over 40% of RAM outside the queue). Each card
has the evidence and at most one action (a button with--control, else the command to copy) and can be
dismissed for 10 minutes in that browser.status --jsongainsexceptions[]andgates[](additive,
schema 1) andheavyq whylists each exception in oneNeeds you:line. Seedocs/dashboard.md. - Ledger v2: every run is bound to the code it ran on. History lines gain
v(schema,2),id(a
ULID that sorts by time),repo(hash of the git common dir, shared by all work trees),worktree,
subdir,commit,tree,dirty,session,itemandgate. Lines written by older versions (no
v) keep loading. Remote runs record the commit that was shipped, its tree, anddirty: false. Outside
a git repository the identity fields stay empty. - Tree identity for dirty work trees. A clean tree is identified by
HEAD's tree id, exactly what the
--cachekey already used. A dirty one is<HEAD tree>+<digest>: the digest coversgit diff HEAD --binary
(staged or not) and the names and contents of untracked files that aren't ignored. The same edits give the
same id, any edit changes it, reverting restores the clean id. About 20 ms clean and 35 ms dirty on a 10,000-file repository
(go test ./internal/gitutil -run '^$' -bench TreeIdentity). Dirty trees are still never cached. - Run flags
--session,--itemand--gate, plusHEAVYQ_SESSIONandHEAVYQ_ITEM, recorded in the
ledger. Names are 1-80 characters ofA-Za-z0-9._:-; anything else exits 2. - The Claude Code hook records the session out of band. When it wraps a command it writes
<queue dir>/sessions/<lane>({session_id, at}, atomic, 0600).heavyq <prio>uses it when--session
andHEAVYQ_SESSIONare absent and the file is under 10 minutes old with a valid id. The rewritten command
is unchanged, so exact permission rules keep matching across sessions. Stale files are pruned with dead
tickets. heavyq historyshows the short commit of each run (+when the work tree was dirty);-vadds the
tree, session, item and gate.heavyq.tomlat the git root: per-repository named gates ([[gate]]withname,run,prio,
light,remote) and a reserved[anchor]section. The loader (internal/repoconfig) validates names,
non-emptyrunlists,prio1-9 and remote names, and refuses unknown keys (with the line) and
duplicate gate names. It is trusted like a Makefile, and hooks never execute gates.heavyq gate status [name] [--json]: is this exact code proven? Per gate command,proven,failed
ormissingon the tree checked out now (clean or dirty), with when, lane and run time, read from the
ledger without running anything (about 20 ms). The latest conclusive run on the tree decides, unless the
command is flaky (below); gave-up, cancelled and interrupted runs are inconclusive; a cache hit counts. An unidentifiable tree (a submodule
with edits of its own, no commit, not git) proves nothing and says why. Exit 0 proven, 1 not, 2 usage
error.--jsonis documented indocs/gates.md.heavyq gate run [name] [--parallel] [--keep-going] [--lane NAME]: runs the gate's unproven commands
through the queue exactly likeheavyq <prio> --cache --gate <name> --remote <r> -- sh -c '<command>',
with the gate'sprio,lightandremote. Proven commands are skipped at once; it stops at the first
failure unless--keep-going. Exit 0 only when the ledger proves the whole gate on the code checked out
when it ends.internal/proof: the matching rules behind both (same repo, same tree, the exactsh -ccommand,
exit 0 and a finished run), pure and table-tested.- Flaky and under-load detection (#30). The ledger records the machine as it was when a run was admitted:
load1,free_mb,cores, plus the limits applied to it (max_load,job_mb); local runs use the sample
the resource gate judged, remote runs the probe placement used.heavyq gate status(text and--json)
classifies every failed command:flakywhen on this tree the command both failed and passed. It is
a label, and proof recovers by repetition: proven once its last two runs passed ("proven (flaky: 1 fail /
2 pass on this tree)"), not proven while the latest run failed or only one pass follows the failure
("flaky — re-run once to confirm: heavyq gate run ready";gate runthen really re-runs it, without
--cache),under_loadwhen the
failing run was admitted by the anti-starvation bypass, at or above the load limit, or with less free RAM
than its job budget ("rerun once before debugging"), elsefailed. A failure under load does not make
a command flaky and never breaks a repetition, so a clean rerun proves it.--jsongainscommands[].class,passesandfails, and
reasonnow also carries the evidence.heavyq whyshows the counts in its gate sentence
("1 failed (1 flaky), 0 missing"). Flaky and under-load failures never raise the Tower'sred_gate
exception. Lines without the new fields load as before and are never called under
load. cmd_hashin the ledger (#38). Each line carries the sha256 of the exact argv the run executed, taken
before the command is redacted and cut to 200 bytes. Proofs match on it when the record has one, so a gate
command longer than 200 bytes can now be proven; records without it (written by older versions) still
match by their command string, and a long command they cannot identify staysmissinguntil it runs again.- heavyq proves itself. This repository has a
heavyq.tomlwith gateready(gofmt,go vet,
go test -race), and CI runsheavyq gate run readywith the freshly built binary instead of separate
vet and test steps. heavyq whyends with "The ready gate is proven / not proven on this tree" when the repository has a
heavyq.toml.- Zero-config default gate. A repository with no
heavyq.tomlgets a gate calledready, detected at its
git root:go.modgivesgo vet ./...andgo test ./...;package.jsongives<pm> run <script>for the
typecheck,lintandtestscripts it defines (<pm>from the lockfile:pnpm-lock.yaml,yarn.lock,
bun.lockb/bun.lock, else npm; theecho "no test specified"stub ofnpm initdoes not count);
pytest.ini,pyproject.tomlor a[tool:pytest]section insetup.cfggivespytest;Cargo.tomlgives
cargo test. Several ecosystems at the root add up, in that order.gate status,gate runand thewhy
line use it and call itready (detected);gate status --jsonadds"detected": true. Detection only reads
files (a bounded read,package.jsonparsed as data, script bodies never used) and never runs anything. An
explicitheavyq.tomlalways wins. heavyq init [--agents-md] [--force] [--print]writes that detection down as a commentedheavyq.toml
at the git root: what the file is, the trust model, how to add a gate. It never overwrites an existing file
(exit 1) unless--force;--printwrites to stdout only.--agents-mdadds a short section ("before
saying a task is done, runheavyq gate run ready; exit 1: fix and re-run; exit 75: queue busy, retry
later, never bypass heavyq") toAGENTS.md(created if missing) and toCLAUDE.md(only if it exists),
between `<!-...
v0.3.0
Added
heavyq dash: a local web dashboard. One embedded page, no daemon, no new dependencies. It shows
machines (RAM vs what a job needs, load vs limit, slots), running jobs with CPU and memory, waiting jobs with
the reason per machine and the anti-starvation countdown, identical runs sharing one result, what runs
outside the queue by executable, and insights from history (wait p50/p95, give-ups, forced admissions,
cache hits, busiest lanes).- Loopback only, a random token per start,
HostandOriginchecks, a strict CSP. Read-only unless
started with--control.
- Loopback only, a random token per start,
heavyq status --json: the same state as a versioned JSON snapshot (schema 1).- Operator control:
heavyq cancel <pid>,heavyq reprio <pid> <1-9>,heavyq pause|resume <machine>
(also from the dashboard). Requests go through<queue dir>/ctl, and each job's own process applies them.
A cancelled job exits 78. A running one gets SIGTERM, its whole process tree included, then SIGKILL 10 s
later. - History records more: jobs that gave up or were cancelled (
result), admissions through the
anti-starvation bypass (forced), and CPU time and peak memory of local runs (cpu_s,max_rss_mb). - Likely secrets in command lines (
TOKEN=…,scheme://user:pass@,--password …, well-known token
shapes) are hidden instatus --jsonand the dashboard.
Verify a download (build provenance, signed by GitHub Actions through Sigstore):
gh attestation verify heavyq_0.3.0_linux_amd64.tar.gz --repo LysCongThanh/heavyqv0.2.0
v0.1.1
Changelog
- f5913b5 fix: report the module version when installed with go install
v0.1.0
Changelog
- 0445e56 feat: priority, resource-aware queue for heavy commands with remote runs by commit