cargo-hauler 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.4
+
+### Patch Changes
+
+- 92e168c: Bump `agent-bundle` and `@agent-bundle/runtime` to the pkg.pr.new preview at `42539ff5f`. With agent-bundle#461 a pass-through `tool/before` result no longer auto-approves, so the hook now answers `allow` only when every command in the input was rewritten onto (or already runs through) the hauler exec path, `continue` + `updatedInput` when a rewritten cargo command shares the input with something the daemon does not govern (`cd … && cargo build`, `cargo test | tail`), and plain `continue` (no decision) for every other tool call; it never returns `ask`. Accept the `confirmed` lineage resolution (agent-bundle#486) in ticket attribution.
+
+## 0.4.3
+
+### Patch Changes
+
+- a2c39f3: Bump `agent-bundle` and `@agent-bundle/runtime` to the pkg.pr.new preview at `5775351fb`, which drops the Claude `plugin.json` `hooks` pointer so Claude Code no longer rejects the plugin with "Duplicate hooks file"
+- ccd6a50: Start the auto-spawned daemon with a curated environment (`PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`, `LANG`/`LC_*`, `XDG_*`, `CARGO_HOME`, `RUSTUP_HOME`, `SSL_CERT_*`, `*_proxy`, `CARGO_HAULER_*`) and the state directory as its cwd, so the first client's `RUSTFLAGS`, `CARGO_TARGET_DIR`, `RUSTC_WRAPPER`, or fd-based `MAKEFLAGS` no longer become the base of every other session's builds. `hauler exec` now relays SIGINT/SIGTERM: a brokered ticket is killed before the client exits `130`/`143`, a direct run's cargo process group is terminated instead of orphaned. A ticket that ends other than `done` prints `ticket cc-N <status>[: reason]` with `128 + signal` for signaled runs; a connection lost after the ack names the ticket (`hauler result cc-N`); a direct run prints its spawn error. The ack carries `waitEtaMs` and auto-background decides on queue wait plus runtime, shown as `wait ~Ns, run ~Ns`. A daemon that never accepted within 60 s goes straight to a direct run instead of a start attempt and a second cycle. `--cwd` is resolved against the caller. `CARGO_HAULER_CARGO_BIN` is read from the daemon's own environment. The PATH shim falls back to the real cargo when its hauler entry is gone and `install-shim` says to re-run `--force` after upgrades. Descriptor-based `MAKEFLAGS`/`MFLAGS`/`CARGO_MAKEFLAGS` jobservers are not transported. Heartbeats count from `started`; a failed or unconfirmed detach is reported; `hauler request --session` no longer holds the stop hook (matching `exec --bg`); `await`/`result`/`kill` fail fast on a daemon `error` reply (#55)
+- ab91d88: Harden the daemon's socket and singleton-lock lifecycle. The daemon now listens on `daemon.sock.<pid>` and atomically renames it over `daemon.sock`, so a daemon that lost socket ownership no longer deletes its replacement's socket on the way out (previously both daemons died and their in-flight tickets were reaped as orphaned). `hauler daemon run` acquires the singleton lock before opening the ledger, running migrations, or draining the passthrough spool, so a losing instance touches neither; it re-checks a held lock about once a second for up to ~20 s instead of giving up on the first look, treats a lock written before the current boot as stale whatever its recorded pid, treats a pid it cannot signal (`EPERM`) as unknown rather than alive, and reclaims a stale lock atomically so two cold starters can no longer both start. A second Ctrl-C during shutdown is now swallowed instead of skipping finalizers and leaving the lock and socket behind (#50)
+- d09b2fb: Harden the `tool/before` shell rewrite and its companions. The rewrite now leaves a command untouched when the pinned `bashjsast` parser cannot round-trip it — background `&`, the `time` keyword, `|&`, `coproc`, and a heredoc feeding a pipeline previously came back as a blocking, un-timed, or syntactically broken command. It no longer passes `--cwd`, so `cd crates/foo && cargo build` builds in `crates/foo`; it skips `command -v/-V cargo`, `type cargo`, and `which cargo`; wraps the unbrokered half of `hauler exec -- cargo build && cargo test`, `while ! cargo build`, and `rustup run <toolchain> -- cargo`. The `cargo clean` guard distinguishes a busy daemon (probe timeout → brokered so the lane serializes the clean) from an absent one (raw run). `tool/after` announces only background or detached tickets, never a foreground run the agent just watched. The stop route clamps `CARGO_HAULER_STOP_WAIT_MS` to the 2 h await ceiling, and `hook-state.json` is written atomically with per-session deny-counter pruning. (#56)
+- df912ae: Honour `hauler kill` for a job parked at the admission gate or on the permit semaphore (it settles `killed` at once instead of blocking its lane until a permit frees), never fold a kill-requested queued job into a batch, clamp the queue ETA so an overrunning lane head no longer cancels queued work and count a head parked at the gate, and finish every settlement step (waiters, lane release, follower exits) even when a ledger write fails. Late attachers receive each replayed chunk exactly once, a follower whose leader exits during registration stays settled (attach/running ledger writes never reopen a terminal row), an early follower release can no longer surface as a `pump failed` cargo termination, and identity attach requires callers to agree on `mergeStderr`. When the shared jobserver FIFO is armed the daemon no longer sets `CARGO_BUILD_JOBS`; `CARGO_HAULER_JOBS_GRANT` applies only while the FIFO is unavailable. (#51, #52, #54)
+- 3f70b60: Keep the daemon responsive and its storage bounded. Kache priors are refreshed without blocking the event loop: the `events.jsonl` tail is read asynchronously from a persisted byte offset and parsed in yielding slices, and the `index.db` aggregate is recomputed only when the file changes on disk. The ledger gains a startup retention pass — finished requests older than `CARGO_HAULER_LEDGER_RETENTION_DAYS` (default `30`) or beyond `CARGO_HAULER_LEDGER_MAX_ROWS` (default `50000`) are deleted with their transitions; `0` disables either limit — the attachment-savings backfill runs once per database (`PRAGMA user_version`) through the rowid index instead of on every open, and request/transition writes commit atomically. NDJSON client lines are capped at 16 MiB: an oversize line gets a `bad-message` error and the connection is closed. Numeric `CARGO_HAULER_*` overrides that do not parse or fall outside their range now log a warning and keep the default instead of silently disabling the arm; `0` or `off` still disables where documented, `CARGO_HAULER_MEM_PRESSURE_SOFT` must stay below `CARGO_HAULER_MEM_PRESSURE_HARD`, and `CARGO_HAULER_BATCH=false|off|no` disables batching like `0` (#57).
+- dd778ab: Fold `cargo test` / `cargo nextest run` requests only when their test selection is identical — same `--test` targets, name filters, arguments after `--`, and nextest filterset — so a composite runs exactly what each participant asked for over the union of their packages (`cargo test -p a` + `cargo test -p b` → `cargo test -p a -p b --no-fail-fast`), never a foreign target or filter. When a composite fails, a folded participant inherits the failure only if it named every package the composite ran; otherwise it is requeued and runs alone instead of reporting another package's failure as its own. Unmodeled post-subcommand options that take a value (`-j`/`--jobs`, `--color`, `--message-format`, `-Z`, `--config`, and nextest's `--retries`, `--test-threads`, `-P`, …) now consume that value instead of recording it as a test-name filter (#53).
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -140,8 +140,8 @@ the same filter as its `session` field). Results carry
 | `tool:hauler/hauler_request` · `cli:request` | submit a background request | `RequestDocument` |
 | `cli:daemon` | `run` / `start` / `stop` / `status` | plain JSON, exit code from the result |
 | `event:session/start` | new session | daemon state and the no-kill rule as context |
-| `event:tool/before` | shell tool about to run | rewrites `cargo …` to `hauler exec --session … --host … -- cargo …`; denies `cargo clean` during in-flight builds |
-| `event:tool/after` | shell tool finished | injects finished-ticket results once per session |
+| `event:tool/before` | shell tool about to run | rewrites `cargo …` to `hauler exec --session … --host … -- cargo …`; denies `cargo clean` during in-flight builds, brokers it while the daemon is too busy to answer |
+| `event:tool/after` | shell tool finished | injects finished background-ticket results once per session |
 | `event:stop` | agent stopping | holds the stop while a foreground ticket is pending (bounded, re-deniable) |
 
 ### Skills
@@ -216,7 +216,7 @@ executable beside it (`dist/bin/cargo-hauler.js` in the package,
 
 | Command | Behavior |
 | --- | --- |
-| `hauler exec [--session ID] [--host HOST] [--cwd DIR] [--bg] -- <cargo …>` | Submit Cargo through the daemon and stream output; hooks rewrite commands to this form. |
+| `hauler exec [--session ID] [--host HOST] [--cwd DIR] [--bg] -- <cargo …>` | Submit Cargo through the daemon and stream output; hooks rewrite commands to this form. A relative `--cwd` is resolved against the caller's directory. Exits with cargo's code; `130`/`143` after a SIGINT/SIGTERM (the ticket is killed first); `75` when auto-backgrounded. |
 | `hauler status [--limit N] [--cwd DIR] [--session ID] [--lane KEY] [--ticket ID …] [--status S …] [--command-contains TEXT]` | Queue, active runs, lanes, admission, kache, optionally filtered. |
 | `hauler log [--limit N]` | Recent requests from the ledger. |
 | `hauler last` | The most recent request. |
@@ -264,9 +264,23 @@ The hook parses the shell command and rewrites each Cargo invocation to
 `hauler exec --session … --host … -- cargo …`. It recognizes `cargo` behind an
 absolute path (`~/.cargo/bin/cargo`), and behind the wrappers agents actually
 use: `env -u VAR X=y cargo …`, `timeout 600 cargo …`,
-`rustup run <toolchain> cargo …`, `stdbuf`, `nice`, `ionice`, `nohup`,
-`time`, `strace`, `sudo`, `xargs`, `command`, `exec`, and `builtin`. Other
-`rustup` subcommands and already-wrapped commands are left alone.
+`rustup run <toolchain> [--] cargo …`, `stdbuf`, `nice`, `ionice`, `nohup`,
+`/usr/bin/time`, `strace`, `sudo`, `xargs`, `command`, `exec`, `builtin`,
+and a negated test (`while ! cargo build; do …`). Other `rustup`
+subcommands, lookups (`command -v cargo`, `type cargo`, `which cargo`), and
+already-wrapped invocations are left alone; in a partially wrapped list
+(`hauler exec -- cargo build && cargo test`) only the unwrapped half is
+rewritten. The rewrite never passes `--cwd`: the command runs in the same
+shell, so `hauler exec` inherits the working directory and
+`cd crates/foo && cargo build` builds in `crates/foo`.
+
+Before rewriting, the hook checks that the parser can reproduce the original
+command token for token. Constructs the pinned parser cannot round-trip —
+a background `&` (`nohup cargo build … &`, `cargo build & pid=$!`), the
+`time` keyword, `|&`, `coproc`, a heredoc that feeds a pipeline or is
+followed by another statement, `elif`, and `function name { … }` — are left
+untouched and run as plain Cargo rather than risk emitting a changed
+command.
 
 A lane is keyed by workspace root and resolved target directory. It runs one
 job at a time. Different lanes may run concurrently after acquiring one of the
@@ -288,8 +302,17 @@ Each admitted leader starts one Cargo process. Identity, coverage, and folded
 batch requests share that process and receive its streamed output. A failed
 stronger compile does not satisfy a coverage or compile-batch attachment; the
 attached request returns to its lane unless its required compilation units were
-already observed as successful. Folded tests share the composite process,
-output, and exit code.
+already observed as successful. Folded tests share the composite process and
+output. `cargo test` / `cargo nextest run` requests fold only when their test
+selection is identical — the same `--test` targets, name filters, arguments
+after `--`, and nextest filterset — so only the package set differs:
+`cargo test -p a` and `cargo test -p b` become
+`cargo test -p a -p b --no-fail-fast`. On success every participant shares
+the exit. When the composite fails, a participant inherits that failure only
+if it named every package the composite ran; otherwise the failing tests may
+belong to another participant's package, so it is requeued and runs alone
+(cargo's test output does not attribute failures to packages). The leader
+keeps the composite exit, as compile-batch leaders do.
 
 Brokered output keeps cargo's stdout and stderr as separate channels. When the
 caller's own stdout and stderr are the same open file (`cargo run 2>&1`, a
@@ -324,18 +347,22 @@ heartbeats. Non-compiling cargo subcommands (`fmt`, `update`, `fetch`, `add`,
 `remove`, `generate-lockfile`, `vendor`, `new`, `init`, `info`, `uninstall`)
 run locally instead of queueing for a permit.
 
-The per-run `CARGO_BUILD_JOBS` grant defaults to the available cores divided
-across the configured permit count, with a floor of four jobs. Separately, the
-daemon arms one GNU make jobserver FIFO with `cores - 1` tokens when it
+The daemon arms one GNU make jobserver FIFO with `cores - 1` tokens when it
 acquires the singleton lock and passes it to every Cargo it spawns through
 `MAKEFLAGS`, so concurrent lanes share one global rustc parallelism budget.
+While the FIFO is armed no `CARGO_BUILD_JOBS` is injected, because Cargo only
+joins an inherited jobserver when `-j`/`build.jobs` is unset. The per-run
+`CARGO_BUILD_JOBS` grant — the available cores divided across the configured
+permit count, with a floor of four jobs — is the fallback for a daemon that
+could not arm the FIFO (no `mkfifo`, unwritable state directory). A caller's
+own `-j` flag or `CARGO_BUILD_JOBS` always wins over both.
 
 | Capability | Behavior |
 | --- | --- |
 | Work sharing | Identical requests attach, covered checks attach, and compatible queued compile or test requests fold. |
 | Lane isolation | A workspace-root and target-directory pair is serialized independently from other lanes. |
 | Admission | Per-core load, Linux CPU PSI, Linux memory PSI and `MemAvailable`, macOS VM pressure, configured thresholds, and the global permit cap control new starts. |
-| Parallelism | A per-run `CARGO_BUILD_JOBS` grant plus one daemon-owned jobserver FIFO shared by every spawned Cargo. |
+| Parallelism | One daemon-owned jobserver FIFO shared by every spawned Cargo; a per-run `CARGO_BUILD_JOBS` grant only when the FIFO could not be armed. |
 | Scheduling | EWMA estimates, optional kache priors, fan-out, dependency topology, recent edits, and request age determine lane order. |
 | Persistence | Tickets, output tails, timings, outcomes, and savings are stored in SQLite. |
 | Caller output and status | Output streams to attached callers; late callers receive buffered replay. After 30 seconds without output, the client emits a progress heartbeat every 15 seconds with lane queue position, the lane-head ticket, and an aggregate wait ETA. |
@@ -351,19 +378,37 @@ immediately. A synchronous request also switches to background mode when a
 *measured* estimate — EWMA history or kache priors, never the cold-start
 default — exceeds the host's shell-tool cap (nine minutes for Claude, ten for
 Codex, fourteen for Cursor; the PATH shim uses `CARGO_HAULER_HOST` when it is
-exported, otherwise the Claude cap). That conversion exits `75`
-(`EX_TEMPFAIL`) with the ticket on stderr, so `cargo build && …` chains and
-scripts cannot mistake "submitted" for "built"; explicit `--bg` keeps exit
+exported, otherwise the Claude cap). The estimate that is compared is the
+whole wait: the work queued ahead in the lane plus the job's own runtime,
+which the queued line reports as `wait ~Ns, run ~Ns`. That conversion exits
+`75` (`EX_TEMPFAIL`) with the ticket on stderr, so `cargo build && …` chains
+and scripts cannot mistake "submitted" for "built"; explicit `--bg` keeps exit
 `0`. Failed runs feed the estimate history too, so a broken build is not
 re-estimated cold on every retry.
 
-The `tool/after` route checks session tickets and, on the first tool call
-after a ticket finishes, adds its result to the agent context. For foreground
-tickets, the `stop` route waits for the lower of the remaining estimate and
-`CARGO_HAULER_STOP_WAIT_MS`; if the ticket finishes it denies the stop and
-returns the result, otherwise it denies with status and ETA. `stopHookActive`
-and an eight-denial cap per ticket prevent a repeated stop loop; background
-tickets never hold a stop. Codex 0.147.0 stop-hold behaviour is verified in
+A foreground `hauler exec` that receives SIGINT or SIGTERM (Ctrl-C, or a
+`timeout N …` wrapper) asks the daemon to kill its ticket, waits for the
+answer, and exits `130` or `143`; in a direct run it terminates the cargo
+process group the same way. A ticket that ends other than `done` is reported
+on stderr as `ticket cc-N <status>[ (signal)][: reason]`, and its exit code is
+cargo's, `128 + signal` for a signaled run, or `1` when the daemon could not
+start cargo at all. If the connection drops after the ticket was accepted, the
+client prints `connection to daemon lost; ticket cc-N continues — hauler
+result cc-N` and exits `1`; the daemon finishes the ticket on its own.
+
+The `tool/after` route checks the session's background tickets — `--bg`,
+`hauler_request`, and synchronous requests the client converted to a ticket
+— and, on the first tool call after one finishes, adds its result to the
+agent context. A foreground ticket streamed its exit to the shell the agent
+just watched, so it is never re-announced. For foreground tickets, the
+`stop` route waits for the lower of the remaining estimate and
+`CARGO_HAULER_STOP_WAIT_MS` (clamped to the daemon's two-hour await
+ceiling); if the ticket finishes it denies the stop and returns the result,
+otherwise it denies with status and ETA. `stopHookActive` and an
+eight-denial cap per ticket prevent a repeated stop loop; the per-ticket
+counters live in `hook-state.json`, written atomically and pruned once a
+session's tickets are no longer pending. `--bg` tickets never hold a stop.
+Codex 0.147.0 stop-hold behaviour is verified in
 [docs/codex-hooks.md](docs/codex-hooks.md).
 
 ### PATH shim
@@ -375,7 +420,11 @@ When the daemon starts Cargo it sets `CARGO_HAULER_INSIDE=1`, and the shim then
 invokes the embedded Cargo directly, so the daemon's own Cargo never returns
 through the broker. The shim is POSIX-only; its directory must appear before
 rustup's Cargo directory on `PATH`; replacing an existing destination requires
-`--force`.
+`--force`. The embedded `hauler` entry lives in a versioned plugin directory:
+when that file no longer exists (an upgrade replaced the directory), the shim
+runs the embedded Cargo directly instead of failing, and `install-shim` says
+so — re-run `hauler install-shim --force` after such an upgrade to route
+scripted Cargo through the broker again.
 
 ### Caller environment
 
@@ -388,10 +437,24 @@ Cargo, so `FOO=bar cargo build` reaches `build.rs`, `env!()`, `cargo run`, and
 for coalescing is digested from the build-relevant subset only (`CARGO_*`,
 `RUST*`, `CC`/`CXX`/`AR`/`CFLAGS`/`CXXFLAGS`/`LDFLAGS` with target-suffixed
 forms, and `PKG_CONFIG_PATH`); pass knobs a `build.rs` reads through
-`--config 'env.FOO="bar"'` when they must also split identity.
+`--config 'env.FOO="bar"'` when they must also split identity. One value is
+filtered rather than forwarded: a `MAKEFLAGS`, `MFLAGS`, or `CARGO_MAKEFLAGS`
+carrying a descriptor-based jobserver (`--jobserver-auth=R,W`,
+`--jobserver-fds=R,W`) names file descriptors that exist only in the caller,
+so it is dropped and the daemon's shared FIFO jobserver applies; a
+`fifo:PATH` jobserver travels as-is.
 `hauler request` and `hauler_request` submit without a caller environment;
 their Cargo processes run with the daemon's environment.
 
+The daemon's own environment is deliberately small. When a client starts it,
+the daemon receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`,
+`LANG` and `LC_*`, `XDG_*`, `CARGO_HOME`, `RUSTUP_HOME`, `SSL_CERT_*`, the
+`*_proxy` variables, and every `CARGO_HAULER_*` setting, with the state
+directory as its working directory. The starting shell's `RUSTFLAGS`,
+`CARGO_TARGET_DIR`, `RUSTC_WRAPPER`, `CARGO_BUILD_*`, `MAKEFLAGS`, `CC`, and
+similar build knobs are not inherited, so they cannot become the silent base of
+every other session's builds.
+
 ### Kache integration
 
 When [kache](https://github.com/ScriptedAlchemy/kache) is available,
@@ -407,27 +470,32 @@ is reported as unavailable and never rejects a request.
 | Variable | Default | Meaning |
 | --- | --- | --- |
 | `CARGO_HAULER_STATE_DIR` | Per-user cache directory | Unix socket or Windows named pipe source, SQLite ledger, daemon log, pid lock, `hook-state.json`, and `hook-events.jsonl`. No legacy alias. |
-| `CARGO_HAULER_CARGO_BIN` | `$CARGO_HOME/bin/cargo` | Cargo binary for daemon-started work; bare `cargo` is the last fallback. Never resolved through `PATH`. |
-| `CARGO_HAULER_MAX_CONCURRENT` | `5` | Global admission permits for Cargo processes across all lanes. |
-| `CARGO_HAULER_JOBS_GRANT` | `max(4, cores / max concurrent)` | `CARGO_BUILD_JOBS` added to each Cargo process; `0` disables injection. |
+| `CARGO_HAULER_CARGO_BIN` | `$CARGO_HOME/bin/cargo` | Cargo binary for daemon-started work; bare `cargo` is the last fallback. Never resolved through `PATH`. Read from the daemon's own environment (export it where the daemon starts, or before `hauler daemon start`); clients do not forward it. |
+| `CARGO_HAULER_MAX_CONCURRENT` | `5` | Global admission permits for Cargo processes across all lanes; an integer >= 1. |
+| `CARGO_HAULER_JOBS_GRANT` | `max(4, cores / max concurrent)` | `CARGO_BUILD_JOBS` added to each Cargo process only while the shared jobserver FIFO is not armed; an armed daemon injects `MAKEFLAGS` instead and leaves `CARGO_BUILD_JOBS` unset. `0` disables injection. |
 | `CARGO_HAULER_LOAD_THRESHOLD` | Disabled | Per-core one-minute load threshold for deferring new admissions. |
 | `CARGO_HAULER_LOAD_MIN` | `2` | Active Cargo processes below which load, CPU PSI, and soft memory pressure do not defer admission. |
-| `CARGO_HAULER_CPU_PRESSURE_THRESHOLD` | `75` | Linux CPU PSI `some avg10` percentage for deferring new admissions; `0` disables. |
-| `CARGO_HAULER_MEM_PRESSURE_SOFT` | `10` (Linux) | Memory PSI `full avg10` percentage for soft deferral; `0` disables. |
-| `CARGO_HAULER_MEM_PRESSURE_HARD` | `20` (Linux) | Memory PSI `full avg10` percentage for hard deferral, confirmed by `full avg60` at half the value; `0` disables. |
-| `CARGO_HAULER_MEM_AVAILABLE_MIN_GB` | `8` (Linux) | `MemAvailable` floor in GiB for hard deferral; `0` disables. |
-| `CARGO_HAULER_MEM_PRESSURE_LEVEL` | `2` (macOS) | Kernel VM pressure level that starts soft deferral (`2` warn, `4` critical). |
+| `CARGO_HAULER_CPU_PRESSURE_THRESHOLD` | `75` | Linux CPU PSI `some avg10` percentage for deferring new admissions; `0` or `off` disables. |
+| `CARGO_HAULER_MEM_PRESSURE_SOFT` | `10` (Linux) | Memory PSI `full avg10` percentage for soft deferral; `0` or `off` disables. Must stay below the hard threshold, otherwise both revert to their defaults. |
+| `CARGO_HAULER_MEM_PRESSURE_HARD` | `20` (Linux) | Memory PSI `full avg10` percentage for hard deferral, confirmed by `full avg60` at half the value; `0` or `off` disables. |
+| `CARGO_HAULER_MEM_AVAILABLE_MIN_GB` | `8` (Linux) | `MemAvailable` floor in GiB for hard deferral; `0` or `off` disables. |
+| `CARGO_HAULER_MEM_PRESSURE_LEVEL` | `2` (macOS) | Kernel VM pressure level that starts soft deferral (`2` warn, `4` critical); `0` or `off` disables. |
 | `CARGO_HAULER_HEAVY_MEM_AVAILABLE_GB` | `16` (Linux) | `MemAvailable` in GiB below which concurrent heavy leaders (release/perf/bench profiles, workspace-wide runs) are capped; `0` or `off` disables the cap. |
 | `CARGO_HAULER_HEAVY_MAX_CONCURRENT` | `1` | Heavy leaders admitted at once while the cap is active. |
 | `CARGO_HAULER_REPLAY_BUFFER_BYTES` | `4194304` | Leader output retained in memory for late-attacher replay. |
 | `CARGO_HAULER_KACHE_INDEX` | kache's configured store | kache index for per-crate timing priors; an empty string disables it. |
-| `CARGO_HAULER_BATCH` | Enabled | `0` disables the batch composer. |
+| `CARGO_HAULER_BATCH` | Enabled | `0`, `false`, `off`, or `no` disables the batch composer. |
 | `CARGO_HAULER_BATCH_WINDOW_MS` | `150` | Delay applied to a batchable lane head so nearby requests can fold; `0` disables. |
 | `CARGO_HAULER_KILL_GRACE_MS` | `8000` | Time between SIGTERM and SIGKILL when the daemon stops a Cargo process. |
-| `CARGO_HAULER_STOP_WAIT_MS` | `30000` | Maximum wait for one stop-hook invocation. |
+| `CARGO_HAULER_STOP_WAIT_MS` | `30000` | Maximum wait for one stop-hook invocation; values above the 7200000 ms await ceiling are clamped. |
+| `CARGO_HAULER_LEDGER_RETENTION_DAYS` | `30` | Finished ledger rows older than this many days are deleted when the daemon starts; `0` disables the age limit. |
+| `CARGO_HAULER_LEDGER_MAX_ROWS` | `50000` | Total ledger rows beyond which the oldest finished rows are deleted when the daemon starts; `0` disables the row cap. |
 | `CARGO_HAULER_LOG_LEVEL` | `Info` | Daemon log level. |
 | `CARGO_HAULER_HOST`, `CARGO_HAULER_SESSION` | Unset | Default `--host` and `--session` attribution for `hauler exec`; the PATH shim also borrows `CARGO_HAULER_HOST`'s shell cap for auto-background. |
 
+A numeric value that does not parse or falls outside its range is reported
+as a warning (daemon log, or stderr for hand-run commands) and the default
+applies; only `0` or `off` disables an arm that documents that contract.
 Each `CARGO_HAULER_*` tuning value takes precedence over its retained legacy
 `CARGO_CONDUCTOR_*` alias; `CARGO_CONDUCTOR_STATE_DIR` is ignored and hand-run
 commands warn when it is still exported (see
@@ -445,7 +513,8 @@ unset, the daemon reads kache's configured local store from
   command through, and a client that cannot reach the daemon makes one
   auto-start attempt and then invokes Cargo directly. A daemon that is alive
   but too loaded to accept within 2 seconds is not treated as absent: `exec`
-  retries for up to 60 seconds before falling back to a direct run.
+  retries for up to 60 seconds, then runs Cargo directly without a start
+  attempt or a second retry cycle.
 - The plugin's own documents never fail open: `hauler_result` and
   `hauler_await` fail loudly when the daemon is unreachable instead of
   reporting a ticket as not found; `hauler_status`, `hauler_log`, and
@@ -454,6 +523,11 @@ unset, the daemon reads kache's configured local store from
 - Test sharing uses identity attachment or batch folding, never coverage.
   Folded `test` and `nextest` requests receive the composite output and exit
   code, so a failure may come from another package in the batch.
+- The `cargo clean` guard probes the daemon for 250 ms. Active work denies
+  the clean; an idle daemon brokers it; a daemon that accepts but does not
+  answer in time is busy, so the clean is brokered and the lane serializes
+  it behind the builds it would otherwise race; only a socket nobody listens
+  on (`ECONNREFUSED`, `ENOENT`) lets a raw `cargo clean` run.
 - Hook rewrites, policy denials such as `cargo clean` during an active build,
   and malformed requests are recorded (`hook-events.jsonl`; a failed ledger
   row).
@@ -478,7 +552,7 @@ data is the daemon's own. The repository ships no preview harness of its own.
 
 agent-bundle does not yet have an npm release; this repository pins the
 [pkg.pr.new](https://pkg.pr.new) preview of main commit
-[`886b1921f`](https://github.com/ScriptedAlchemy/agent-bundle/commit/886b1921f64f7b857528acda32d94c4d0df9bba7)
+[`42539ff5f`](https://github.com/ScriptedAlchemy/agent-bundle/commit/42539ff5fbafdff0656317b841a50100ac0fc141)
 for both `agent-bundle` and `@agent-bundle/runtime`. `inspect` reports the
 `agent` component kind as unavailable on every host (agent-bundle G5
 deferral); this plugin defines no agents. Two framework limitations observed