Skip to content

Releases

v0.5.2

Choose a tag to compare

@github-actions github-actions released this 03 Nov 02:20
Immutable release. Only release title and notes can be modified.
d56bf7c

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 ends PASS? with a warning quoting the line, is recorded as suspect (never as proof, never cached) and still exits 0; --strict, gates and item proofs make it exit 127. A sh -c string with a pipe draws a one-time warning about the last-stage exit status, and gate commands run under bash -o pipefail where 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.gz

v0.5.1

Choose a tag to compare

@github-actions github-actions released this 02 Nov 18:22
Immutable release. Only release title and notes can be modified.
9647321

Added

  • --with REPO[@REF], now complete. A command that reads ../shared-schema or ../core-lib declares 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 local exits 2 naming the sibling, and auto uses the remotes only. Siblings are part of the run id, so --cache works with them and a sibling at another commit is never a cache hit or a proof; status, status --json, history -v and the ledger show with: 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 set with = ["shared-schema@v2.1.0"] and need_gh = true; heavyq gate run passes them to every command, and gate status looks for runs on the same sibling commits. The JSON schemas are updated.

Fixed

  • install.sh --verify names 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.gz

v0.5.0

Choose a tag to compare

@github-actions github-actions released this 02 Nov 16:43
Immutable release. Only release title and notes can be modified.
f6373ee

Added

  • Signed releases. Every archive and checksums.txt now 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 show cosign verify-blob and
    gh attestation verify. Releases are immutable (repository setting), and v* tags are protected from deletion
    and force-push (ruleset).

  • install.sh, attached to every release and listed in its signed checksums.txt: detects OS and CPU,
    downloads the archive, checks its SHA-256 against checksums.txt (a mismatch or a duplicated line installs
    nothing), installs into ~/.local/bin or --prefix DIR/bin atomically, and with --verify also checks the
    cosign signature. --version pins a release. Tested in CI on Linux and macOS against a local fake release and
    against real releases (docs/install.md).

  • heavyq <command> --help (and heavyq 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 --help after -- 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 by tools/mangen and 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/ for heavyq.toml, the user config and heavyq status --json, generated from the
    Go types by tools/schemagen (a separate module, so the main module keeps its single dependency). Add
    #:schema https://raw.githubusercontent.com/LysCongThanh/heavyq/main/schema/heavyq.schema.json as 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 as additionalContext on startup, resume and compact, so /compact cannot erase
      the thread. Silent in a repository that never used heavyq.
    • heavyq steer off|guard|destroy, stored per repository in the git common dir (default off;
      HEAVYQ_STEER overrides it, off is 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). guard blocks
      at most 3 times per session and honours stop_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. destroy has no cap, also gates SubagentStop,
      TaskCompleted and TeammateIdle (exit 2 with the reason on stderr) and repeats the brief in every block;
      heavyq steer destroy prints how to lift Claude Code's native cap (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=0) and
      --apply writes it to the Claude Code settings env block (a .bak is 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 doctor looks 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 (default queue; the exact set, foreign hooks are
      kept) and the plugin's hooks.json now carry SessionStart, Stop, SubagentStop, TaskCompleted and
      TeammateIdle, behind the same command -v heavyq guard. 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.RunWithin and 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 as status --json and 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|line or m at runtime (the last one is
    remembered in $XDG_STATE_HOME/heavyq/top-mode); --line / --once print one frame for tmux
    status-right or scripts. Keys: j k g G Tab, Enter (why), / filter, r, ?, y (copy, OSC 52),
    q; with --control, c (inline y/n), + - (priority) and p (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 is golang.org/x/term (raw mode and terminal size).
    Humans only: the help agents card is unchanged.

  • macOS remotes: run heavy jobs on a spare Mac (docs/remote.md).
    A stock Mac (no flock, no setsid, 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 same flock(2) on the same
    lock files, so busy slots look the same to the probe) and POSIX::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 reads sysctl and vm_stat through 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-remote env_path key 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. --share rounds 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-protected GET /api/v1/receipts?window=day|week|month.

  • Mentor: break repeat failures, measured with a holdout (internal/mentor, docs/mentor.md).
    The same run_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, with Next: <one action>. at
    the 3rd. Never for 124, 137, 130, 143 or heavyq's own 75-78 and 255, never for under_load or 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 both PostToolUse and PostToolUseFailure, 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 prints additionalContext only for the inject arm. Every eligible event is logged
    to mentor/interventions.jsonl with its rule, seed, arm (a seeded 80/20 draw), event and outcome (did the next
    heavy run differ, by run_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 = 100 is shadow mode), HEAVYQ_MENTOR=off, and
    ledgerindex.LaneRuns (a lane's newest records from the index). The settings entry is documented; hook install does no...

Read more

v0.4.0

Choose a tag to compare

@github-actions github-actions released this 01 Nov 21:51
83be598

Added

  • macOS parity: RAM/load gate, CPU attribution, process-tree cancel (no cgo). Local metrics come from
    sysctl -n hw.memsize hw.ncpu vm.loadavg and vm_stat (available = free + inactive + purgeable +
    speculative pages, capped at installed RAM), so heavyq status --json has metrics_known: true on a Mac.
    Processes come from ps -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 the ps ppid map and reaches every grandchild still attached to its parent;
    orphans re-parented to launchd can 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 a macos job.
  • 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, enter triggers, exit conditions, 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/*.md over
    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>), within inject_tokens (default 150, max 400,
    about 4 bytes per token). enter.stall stays 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. See docs/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 of force_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 --json gains exceptions[] and gates[] (additive,
    schema 1) and heavyq why lists each exception in one Needs you: line. See docs/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, item and gate. Lines written by older versions (no
    v) keep loading. Remote runs record the commit that was shipped, its tree, and dirty: 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
    --cache key already used. A dirty one is <HEAD tree>+<digest>: the digest covers git 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, --item and --gate, plus HEAVYQ_SESSION and HEAVYQ_ITEM, recorded in the
    ledger. Names are 1-80 characters of A-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
    and HEAVYQ_SESSION are 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 history shows the short commit of each run (+ when the work tree was dirty); -v adds the
    tree, session, item and gate.
  • heavyq.toml at the git root: per-repository named gates ([[gate]] with name, run, prio,
    light, remote) and a reserved [anchor] section. The loader (internal/repoconfig) validates names,
    non-empty run lists, prio 1-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
    or missing on 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. --json is documented in docs/gates.md.
  • heavyq gate run [name] [--parallel] [--keep-going] [--lane NAME]: runs the gate's unproven commands
    through the queue exactly like heavyq <prio> --cache --gate <name> --remote <r> -- sh -c '<command>',
    with the gate's prio, light and remote. 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 exact sh -c command,
    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: flaky when 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 run then really re-runs it, without
    --cache), under_load when 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"), else failed. A failure under load does not make
    a command flaky and never breaks a repetition, so a clean rerun proves it. --json gains commands[].class, passes and fails, and
    reason now also carries the evidence. heavyq why shows the counts in its gate sentence
    ("1 failed (1 flaky), 0 missing"). Flaky and under-load failures never raise the Tower's red_gate
    exception. Lines without the new fields load as before and are never called under
    load.
  • cmd_hash in 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 stays missing until it runs again.
  • heavyq proves itself. This repository has a heavyq.toml with gate ready (gofmt, go vet,
    go test -race), and CI runs heavyq gate run ready with the freshly built binary instead of separate
    vet and test steps.
  • heavyq why ends 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.toml gets a gate called ready, detected at its
    git root: go.mod gives go vet ./... and go test ./...; package.json gives <pm> run <script> for the
    typecheck, lint and test scripts it defines (<pm> from the lockfile: pnpm-lock.yaml, yarn.lock,
    bun.lockb/bun.lock, else npm; the echo "no test specified" stub of npm init does not count);
    pytest.ini, pyproject.toml or a [tool:pytest] section in setup.cfg gives pytest; Cargo.toml gives
    cargo test. Several ecosystems at the root add up, in that order. gate status, gate run and the why
    line use it and call it ready (detected); gate status --json adds "detected": true. Detection only reads
    files (a bounded read, package.json parsed as data, script bodies never used) and never runs anything. An
    explicit heavyq.toml always wins.
  • heavyq init [--agents-md] [--force] [--print] writes that detection down as a commented heavyq.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; --print writes to stdout only. --agents-md adds a short section ("before
    saying a task is done, run heavyq gate run ready; exit 1: fix and re-run; exit 75: queue busy, retry
    later, never bypass heavyq") to AGENTS.md (created if missing) and to CLAUDE.md (only if it exists),
    between `<!-...
Read more

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 01 Nov 16:13
f15f935

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, Host and Origin checks, a strict CSP. Read-only unless
      started with --control.
  • 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 in status --json and 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/heavyq

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 01 Nov 14:04
00305ea

Changelog

  • 96866a5 feat(cache): reuse results by git tree and coalesce identical runs
  • 1e00cae feat(config): add [hook] and [cache] sections
  • 4e141e2 feat(hook): Claude Code PreToolUse hook that queues heavy commands

v0.1.1

Choose a tag to compare

@github-actions github-actions released this 31 Oct 14:20
f5913b5

Changelog

  • f5913b5 fix: report the module version when installed with go install

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 31 Oct 14:16
3d740d6

Changelog

  • 0445e56 feat: priority, resource-aware queue for heavy commands with remote runs by commit