feat: tell the job how large its claim is

[stephenc]

A claim controls the queue, and it does not control the job. A job that asks
the machine how many cores it has receives the number of the MACHINE, so a job
with a claim of 2 cores on a machine of 16 starts 16 threads. It then takes the
capacity that qex gave to the other jobs, and it breaks the promise that it
made.

Most runtimes read a variable in place of the machine. qex now writes those
variables from the resolved claim:

$ qex submit --cpu 2 --mem 2GB -- go run main.go
NumCPU=16 GOMAXPROCS=2

An agent that queues a build, a test suite or a training run thus receives the
share that it asked for, and the other users of the machine keep theirs.

QEX_CPU, QEX_MEM and QEX_MEM_MB hold the claim for your own script, so it
needs no other tool: make -j"$QEX_CPU". The runtimes receive GOMAXPROCS,
GOMEMLIMIT, OMP_NUM_THREADS, OPENBLAS_NUM_THREADS, MKL_NUM_THREADS,
NUMEXPR_NUM_THREADS, VECLIB_MAXIMUM_THREADS, RAYON_NUM_THREADS,
CARGO_BUILD_JOBS, JULIA_NUM_THREADS, DOTNET_PROCESSOR_COUNT,
POLARS_MAX_THREADS, and NODE_OPTIONS with a heap of three quarters of the
claim.

This is the nearest thing to a limit that operates on macOS as well as on
Linux, and it needs no cgroup and no privilege. It stays a promise: a program
that asks the operating system directly still sees the whole machine.

The change of behaviour

A job that gives BOTH --cpu and --mem receives these variables. Every other
job receives none of them:

• A job with no claim receives nothing. The default claim is one core, and a
  job that heard that number would run single-threaded on a large machine.
• A job with a learned claim receives nothing. qex would measure the job that
  it made single-threaded, learn one core, and make the fault permanent.
• A job that gives one half of the claim receives nothing. The other half comes
  from the defaults or from the learning, and that half is not a decision.

qex never replaces a value that is already there. A value from your shell,
from the job file or from --env is a decision that somebody made, and qex
fills the values that nobody chose.

--env-capture none receives no claim either. That mode promises [env] and
--env only, and none means none.

How to turn it off

Use qex submit --no-limit-env-hints for one job. Write
no_limit_env_hints = true in a job file or in a stage of a pipeline. Write
[claims] export_env = false for every job of the machine.

Two variables go the other direction: [claims] also = ["java", "make"] adds
JAVA_TOOL_OPTIONS and MAKEFLAGS. Each of the two has a cost, so neither is
a default. Every JVM writes Picked up JAVA_TOOL_OPTIONS: ... to its standard
error, and that line lands in the log of the job. MAKEFLAGS replaces the -j
of a Makefile that gives one.

A limit for the JVM needs -Xmx, and not -XX:MaxRAMPercentage: the JVM takes
that percentage of the memory of the MACHINE, so a claim of 2GB on a machine of
28GB still gave a heap of 7GB. node has no variable for the number of cores, so
node receives the memory only.

[stephenc]

Pre-merge checklist

• Rebased on main (7927324, after fix: the coordinator reads its configuration again when it changes #7, fix: accept a number where the configuration takes a number or text #6, fix!: give the exit code that says why the job of qex run stopped #40 and docs: say what qex run is for, and what it costs #5)
• The version stays 0.0.0-dev; the branch held a bump, and the rebase dropped it
• cargo fmt --all -- --check and cargo clippy --all-targets -- -D warnings give nothing
• cargo test --bins — 199 pass
• cargo test --test e2e -- --test-threads=2 — 88 pass
• The feature was measured with a real Go program through the queue: NumCPU=16 GOMAXPROCS=2 with --cpu 2 --mem 2GB, and GOMAXPROCS=16 with no claim
• Each new test was mutation tested; the code that survived now has a test

[Copilot]

Pull request overview

This PR ensures jobs are informed of their resolved CPU/memory claim via environment variables so language runtimes and build tools size their thread pools and heaps to the claimed share rather than the full machine.

Changes:

• Export claim-derived env vars (e.g., QEX_CPU, QEX_MEM(_MB), GOMAXPROCS, GOMEMLIMIT, OMP_NUM_THREADS, NODE_OPTIONS, etc.) only when both --cpu and --mem were explicitly provided (and not when --env-capture none is used).
• Add opt-out controls via CLI (--no-limit-env-hints), job files / pipeline stages (no_limit_env_hints = true), and global config ([claims] export_env = false, plus [claims] also = ["java","make"]).
• Add/extend unit + e2e tests and update help/reference documentation to describe the behavior and configuration.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/e2e.rs	Adds end-to-end coverage for when claim env vars are exported, preserved, or suppressed across CLI/job-file/pipeline/config scenarios.
src/spec.rs	Implements claim env export during job resolution, adds the no_limit_env_hints controls, and introduces export_claim with targeted runtime env vars.
src/pipeline.rs	Plumbs no_limit_env_hints from pipeline stages into the generated JobFile spec.
src/help.rs	Documents no_limit_env_hints in job-file help output and introduces [claims] config fields in config help.
src/config.rs	Introduces [claims] configuration (export_env, also) and wires it into the global Config.
src/commands.rs	Passes the new no_limit_env_hints option through submit/run command resolution.
src/cli.rs	Adds the --no-limit-env-hints CLI flag with user-facing help text.
README.md	Updates the README to describe that claims are exported to job environments and never override user-provided values.
docs/reference.md	Adds a reference section documenting exported variables, the “both cpu+mem” rule, and all opt-out / opt-in controls.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.