cargo-hauler 0.4.9 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- cfb8d3c: Make coverage attachment fire in practice, say why it did not, and let a compile-only `cargo test --no-run` ride a running `cargo test`.
+  
+  - A `test --no-run` / `bench --no-run` submitted while a `test` / `bench` with the same packages, target selection, features, and profile is in flight in the lane attaches to it and is released — `done`, exit 0, with the leader's compile time so far as its saved compute — the moment the leader prints Cargo's `Finished` line, while the leader goes on running its tests. The leader's test filters, `--test-threads`, and `--no-fail-fast` do not disqualify the rider; a `--lib` rider never attaches to a `--test foo` leader, or a named-target rider to a default-target one. A leader whose build fails requeues the rider through the existing failed-stronger path; a leader that never reports its build finished (`--quiet`, `CARGO_HAULER_OVERLAP_EXECUTION=0`) releases it at settlement. A rider that arrives after the leader's build already finished is refused (`leader-build-finished`) and runs its own, mostly fresh, cargo at once. Both rows carry `buildFinishedAtMs`. (#88)
+  - Coverage gates widened where safe: flags the daemon does not model (`--locked`, `--offline`, `--message-format`, …) and arguments after `--` disqualify a `check` riding a `build` / `check` only when they differ between the two requests; `check --tests` rides `build --tests` / `build --all-targets`; a `--bin X` / `--example X` rider rides a `--bins` / `--examples` leader. `check` still never rides `clippy` (a lint failure would misreport the check), a `-p` rider is still not proven by a leader compiling its unnamed default package set, and `--tests` does not stand in for a named `--test X`. (#89)
+  - Every refused attachment is logged at debug level (`attach rejected`) with the gate — `subcommand`, `opaque-arguments`, `passthrough`, `compile-surface`, `packages`, `targets`, `channels`, `leader-build-finished` — a one-line detail, and both tickets; the status report counts one refusal per request under `metrics.attach_rejections`, keyed by the nearest gate any leader reached (`hauler status --json`, `hauler_status`). (#89)
+- d5ae3e9: Show what the hauler costs, not only what it saves: queue wait vs run time per metrics window, the compile/execute split per command, and kache store pressure. (#92)
+  
+  - Each metrics window (`1h`, `24h`, `all`) now reports total queue wait against total run time for leaders, and splits the wait by cause: *lane-bound* (a same-lane leader was still compiling — before its `Finished` line or exit), *permit-bound* (every admission permit was held and no same-lane compile was to blame), and *other* (admission holds, `--after` prerequisites, scheduling latency). The classification is a pure sweep over ledger rows, run against the daemon's current permit count; the tile states that assumption, since runs admitted under an earlier cap are classified against today's.
+  - With `buildFinishedAtMs` on the row, the by-command split adds compile vs execution p50s for `test`/`run`/`bench` leaders, and the window reports the lane time the execution-phase hand-back released. Pure compiles have no split and say nothing.
+  - The kache panel (`hauler status`, `hauler_status`, and the dashboard) surfaces store pressure: blob bytes recorded in the index against `local_max_size` (from `KACHE_MAX_SIZE` or kache's `config.toml`; "limit unknown" names why when it cannot be read), the last GC from `gc_stats.json` — when, how long, what it evicted — with any `gc: skipping eviction` warnings matched from kache's `auto-gc.log`/`daemon.log` during that run, and `key_ms` mean/p95 over the events tail. Warnings appear when the store is over its limit or the last GC declined or skipped evictions. Missing or unparsable files render as unavailable with their reason, never as an empty store.
+  - Protocol additions are optional fields (`metrics.windows[].waitSplit`, `handBack`, `runTotalMs`, `waitTotalMs`, `bySubcommand[].phases`, `kache.pressure`); clients reading an older daemon see the tiles as unavailable rather than as zeros.
+- ec9bf65: Fold more queued work into one Cargo run: compile batches with a `--` trailer, and test runs whose filters differ.
+  
+  - `cargo build` / `check` / `clippy` requests with the same arguments after `--` now batch: `cargo clippy -p a -- -D warnings` and `cargo clippy -p b -- -D warnings` run as `cargo clippy -p a -p b -- -D warnings`, the trailer once. Such runs are demultiplexed like any other compile (the `--message-format` rewrite goes before the `--`), so under `-D warnings` a participant whose own units compiled cleanly is released as done when another participant's warnings fail the composite; the rest rerun alone. Trailers that differ, or a trailer on one side only, still keep the runs apart, as do differing `--all-targets` / `--tests` / `--features`. (#86)
+  - `cargo test` requests naming different packages fold even when their bare name filters differ: `cargo test -p a -- f1` and `cargo test -p b -- f2` run as `cargo test -p a -p b --no-fail-fast -- f1 f2`, the union of packages with the union of filters. An identical set of `--test-threads=N`, `--nocapture`, `--quiet` (or `-q`) after `--` folds too, carried once from the leader; a mismatched set does not, and `--exact`, `--skip`, `--ignored`, `--include-ignored`, `--list`, `--format`, `--logfile`, or any other harness flag keeps a run out of composites. `--lib` runs fold like `--test NAME` runs; the target selection still has to match. Requests naming the same packages still need the same filters, and unfiltered runs fold only with unfiltered runs. A folded participant inherits a composite failure only when it asked for every package and every filter the composite ran; otherwise it reruns alone. (#87)
+- c27662d: Estimate compile and execute separately, and keep a realistic queue ETA when a live head overruns.
+  
+  `hauler status` reports `compileEstimateMs`, `executeEstimateMs`, and the current `phase` on a ticket. Followers waiting on a `test`/`nextest`/`bench`/`run` head see only the remaining execution time in `queue.waitEtaMs` (zero once overlap has handed the lane back), and queued tickets ahead of them count only their compile when overlap will hand the lane back. A head that has passed `CARGO_HAULER_STALL_ESTIMATE_FACTOR` times its estimate but is still burning CPU or printing is flagged `estimateState: overrun` with the intent's p90 (`p90Ms`), and its followers see `queue.headEstimateState: overrun`; its remaining time is re-estimated from that p90 — never less than one more estimate's worth — instead of contributing zero to the queue. A silent no-CPU head stays `stalled`. Filtered `--test <name>` runs with no history of their own borrow a same-package neighbor's timing before falling back to the crate-wide prior.
+
+### Patch Changes
+
+- f01833d: Cut what the hooks cost every shell tool call. The `tool/before` and `tool/after` hooks are now declared handlers compiled into standalone entries (`hooks/before-tool-shell-before-*.mjs`, `hooks/after-tool-shell-after-*.mjs`) instead of event routes that loaded the whole rendering runtime before looking at the command. `tool/before` reads `tool_input.command` and answers `continue` at once when it has no `cargo`, `hauler`, or `conductor` word (word-boundary aware; `mycargo` and `CARGO_HOME=… ls` do not match, `~/.cargo/bin/cargo`, `cargo-hauler`, and `echo cargo` do — a doubtful command takes the full path). `tool/after` runs that test plus one bounded 500 ms socket ping (`session-completed` with the session's hook-state cursor, no Effect runtime), and loads the telemetry and notification code only when the command was cargo-related or the daemon reported finished tickets; with no daemon it exits quietly with no output. Rewrite, `cargo clean` denial, `hauler exec` pass-through, and completion notices are unchanged. Measured with `/usr/bin/time -v`, median of 5, Claude `ls -la` envelope: `tool/before` 0.05 s / 48 MB and `tool/after` 0.05 s / 49 MB, against 0.54 s / 143 MB and 0.56 s / 144 MB for the 0.5.0 wrappers without a shared runtime (0.10 s / 64 MB with one, per #90); a `cargo test -p foo` envelope is 0.05 s / 49 MB either way. (#90)
+
+## 0.5.0
+
+### Minor Changes
+
+- b80d9db: Cut the latency the hauler adds on a shared target directory, and stop charging lane wait to attaching.
+  
+  - A lane now hands its slot to the next request as soon as a `test`, `nextest`, `bench`, or `run` leader prints Cargo's `Finished … target(s)` line: Cargo drops the build-directory lock there, so the next compile overlaps the leader's test run instead of waiting for it. The leader keeps its admission permit until it settles. `hauler status` and the dashboard list such leaders under the lane's `executing` tickets, and the ledger stamps `buildFinishedAtMs` on the leader and its riders. `CARGO_HAULER_OVERLAP_EXECUTION=0` restores strict one-process-per-lane.
+  - Default admission permits scale with the machine: one per eight cores, clamped between the previous five and sixteen. `CARGO_HAULER_MAX_CONCURRENT` still overrides.
+  - The cost model times edited and cached runs of an intent separately, and floors an edited intent that has only ever been timed cached at the crate compile priors, so a recompiling test run no longer reaches the head of the lane on a seconds-long estimate; unedited runs no longer teach the per-crate compile priors.
+  - Saved latency for riders is measured from the later of the rider's creation and the leader's start: time queued behind a leader that had not started is lane wait the rider would have paid alone, not a cost of attaching. Existing ledgers recompute the column once on open (`user_version` 2); the dashboard's all-time latency tile changes accordingly.
+
 ## 0.4.9
 
 ### Patch Changes

package/README.md

@@ -130,35 +130,89 @@ 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
-global admission permits. `CARGO_HAULER_MAX_CONCURRENT` controls the
-machine-wide permit count and defaults to five Cargo processes. Attached
-requests (riders) do not hold permits; the admission meter counts permit
-holders and reports riders separately.
+Both shell hooks run on every shell tool call, so they decide cheaply before
+they do anything else. The `tool/before` entry reads `tool_input.command` and
+answers `continue` for a command with no `cargo`, `hauler`, or `conductor`
+word in it (word-boundary aware: `mycargo` and `CARGO_HOME=… ls` are not
+matches, `~/.cargo/bin/cargo`, `cargo-hauler`, and `echo cargo` are — a false
+negative would bypass the broker, so anything that looks like a mention takes
+the full path). Only a matching command evaluates the parser and the rewrite.
+The `tool/after` entry runs the token test and one bounded socket ping to the
+daemon (the `session-completed` request with the session's hook-state cursor,
+500 ms, no Effect runtime); it loads the telemetry and notification code only
+when the command was cargo-related or the daemon reported finished tickets. A
+non-cargo call with nothing finished — or no daemon at all — exits with no
+output. Measured with `/usr/bin/time -v` on a Claude `ls -la` envelope, the
+compiled entries take ~50 ms wall and ~49 MB RSS, against ~100 ms and 64 MB
+for the 0.4.8 event-route wrappers with a shared runtime available and
+~560 ms and 144 MB without one.
+
+A lane is keyed by workspace root and resolved target directory. It compiles
+one job at a time — Cargo's own build-directory lock would serialize them
+anyway. Once a `test`, `nextest`, `bench`, or `run` leader reports its build
+finished, Cargo has dropped that lock, so the lane hands its slot to the next
+request and that compile overlaps the leader's test run
+(`CARGO_HAULER_OVERLAP_EXECUTION=0` restores strict one-at-a-time). Different
+lanes may run concurrently after acquiring one of the global admission
+permits. `CARGO_HAULER_MAX_CONCURRENT` controls the machine-wide permit count;
+the default is one permit per eight cores, clamped between five and sixteen,
+since the shared jobserver already bounds compile parallelism and the pressure
+arms defer admission under load. Attached requests (riders) do not hold
+permits; the admission meter counts permit holders and reports riders
+separately.
 
 Within a lane, the daemon can reduce work in three ways:
 
 1. **Identity attachment:** a byte-identical request attaches to an in-flight
    run.
 2. **Coverage attachment:** a narrower `check` attaches to a compatible
-   `build` or `check` that covers its package and target scope.
+   `build` or `check` that covers its package and target scope (`--tests`
+   under `--tests` or `--all-targets` included); a compile-only
+   `test --no-run` / `bench --no-run` attaches to a running `test` / `bench`
+   with the same packages, target selection, features, and profile — the
+   leader's test filters and `--test-threads` select what runs, not what
+   compiles — and is released as soon as the leader prints its `Finished`
+   line rather than when its tests end. Flags the daemon does not model
+   (`--locked`, `--offline`, …) and arguments after `--` disqualify a pair
+   only when they differ between the two requests. `check` never rides
+   `clippy`: a lint failure would misreport the check.
 3. **Batch folding:** compatible queued compile or test requests are combined
    into one invocation.
 
+A request that could not attach is logged at debug level with the gate that
+refused it (`subcommand`, `opaque-arguments`, `passthrough`,
+`compile-surface`, `packages`, `targets`, `channels`,
+`leader-build-finished`) and both tickets, and `hauler status --json`
+counts refusals per gate under `metrics.attach_rejections` (the nearest
+miss when several leaders were considered).
+
 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 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
+already observed as successful. Compile batches (`build`, `check`, `clippy`)
+require the same target selection and features, and the same arguments after
+`--`: `cargo clippy -p a -- -D warnings` and `cargo clippy -p b -- -D warnings`
+become `cargo clippy -p a -p b -- -D warnings`, with the trailer once. Under
+`-D warnings` another participant's warnings fail the composite; a participant
+whose own units compiled cleanly is still released as done, the rest rerun
+alone. Folded tests share the composite process and output. `cargo test`
+requests fold when their `--test` / `--lib` selection and harness flags match
+— `--test-threads=N`, `--nocapture`, and `--quiet` are the only flags a
+composite carries, and only when every participant asked for the same set.
+Requests naming different packages may also differ in bare name filters:
+`cargo test -p a -- f1` and `cargo test -p b -- f2` become `cargo test -p a -p
+b --no-fail-fast -- f1 f2`, a run over the union of packages with the union of
+filters (a filter for one package may also match test names in another).
+Requests naming the same packages share no compile and still need the same
+filters; unfiltered runs fold only with unfiltered runs; `--exact`, `--skip`,
+`--ignored`, `--include-ignored`, `--list`, `--format`, `--logfile`, or any
+other harness flag keeps a run out of composites. `cargo nextest run`
+requests fold only on an identical filterset. On success every participant
+shares the exit. When the composite
+fails, a participant inherits that failure only if it named every package and
+every filter the composite ran; otherwise the failing tests may belong to
+another participant's package or filter, 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.
 
@@ -172,7 +226,9 @@ stdout.
 
 ![cargo-hauler request normalization, lane-local serialization, scheduling, admission, and concurrent Cargo processes](docs/media/how-it-works.png)
 
-The scheduler estimates run cost from per-intent EWMA history. It can also use
+The scheduler estimates run cost from per-intent EWMA history, split into a
+compile phase and an execution phase once the ledger has seen
+`buildFinishedAtMs` on that intent. It can also use
 per-crate timing data from kache. Lower-cost work, requests with more attached
 callers, dependency-unblocking work, and recently edited packages receive a
 lower scheduling score. Waiting time lowers the score further so broad work
@@ -227,14 +283,14 @@ 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. |
+| Work sharing | Identical requests attach, covered checks and compile-only `test --no-run` requests 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 | 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; `--after cc-N` holds a request until the named tickets settle. |
+| Scheduling | Per-phase EWMA estimates (compile vs execute), optional kache priors, fan-out, dependency topology, recent edits, and request age determine lane order; `--after cc-N` holds a request until the named tickets settle. |
 | Persistence | Tickets, output tails, timings, outcomes, and savings are stored in SQLite; every leader run's whole combined output is kept on disk as `<state dir>/tickets/<ticket>.log`. |
 | 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. |
-| Wait escalation | A queued request waiting longer than the larger of twice its own estimate and ten minutes is flagged as delayed; running jobs silent for more than five minutes show a quiet-duration hint. A running job past three times its estimate whose process tree has burned no CPU and printed nothing for ten minutes is flagged `stalled`; only a stalled job whose submitting connection is gone is killed automatically. |
+| Wait escalation | A queued request waiting longer than the larger of twice its own estimate and ten minutes is flagged as delayed; running jobs silent for more than five minutes show a quiet-duration hint. A live head past three times its estimate that is still burning CPU or printing is flagged `estimateState: overrun` (its followers see `queue.headEstimateState`) and contributes its history p90 remaining — never less than one more estimate's worth — to the queue ETA instead of zero. A running job past three times its estimate whose process tree has burned no CPU and printed nothing for ten minutes is flagged `stalled`; only a stalled job whose submitting connection is gone is killed automatically. |
 | Daemon status | `running`, `stopped`, or `unresponsive`: a socket that exists but does not answer within its budget is reported as unresponsive, never as stopped. |
 
 ### Tickets and long-running requests
@@ -287,7 +343,12 @@ macOS; other platforms do not detect stalls). A ticket is flagged `stalled`
 when its elapsed time exceeds `CARGO_HAULER_STALL_ESTIMATE_FACTOR` (3) times
 its estimate, the tree's CPU time has not changed for
 `CARGO_HAULER_STALL_IDLE_MS` (ten minutes), and it printed nothing in that
-window. `hauler status`, `hauler_status`, and the dashboard show `stalled`
+window. A head that has crossed that estimate multiple but is still burning
+CPU or printing is flagged `estimateState: overrun` instead (with the
+intent's `p90Ms`, and `queue.headEstimateState: overrun` on the tickets
+behind it): the queue ETA uses the intent's p90 remaining — never less than
+one more estimate's worth — rather than zero, and agents can background it
+without treating it as deadlocked. `hauler status`, `hauler_status`, and the dashboard show `stalled`
 with the idle duration; `hauler result` and `hauler_result` answer `ticket
 looks stalled (no CPU for Nm) — hauler kill cc-N`; `hauler await` heartbeats
 say the same. Riders of a stalled leader report the leader's stall and its
@@ -318,7 +379,7 @@ send (`outputPath`, `after`), so a plain version difference alone does not
 break `status`, `result`, or `await`; finish or `hauler kill` what is in
 flight before restarting if the work matters.
 
-The `tool/after` route checks the session's background tickets — `--bg`,
+The `tool/after` hook 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
@@ -385,6 +446,17 @@ reports the slowest crates by profile (`<KacheStats>`). Without that index,
 estimates come from the daemon's EWMA history. A missing or incompatible index
 is reported as unavailable and never rejects a request.
 
+The same panel surfaces store pressure: blob bytes recorded in the index
+against kache's `local_max_size` (from `KACHE_MAX_SIZE` or
+`$XDG_CONFIG_HOME/kache/config.toml`; when neither applies the panel says
+"limit unknown" and why), the last GC from `gc_stats.json` beside the index
+— when it ran, how long it took, what it evicted, and any `gc: skipping
+eviction` warnings from kache's `auto-gc.log`/`daemon.log` during that run —
+and `key_ms` mean/p95 over the tail of the events sidecar. Warnings appear
+when the store is over its limit or the last GC declined or skipped evictions;
+a missing or unparsable file renders as unavailable with its reason, never as
+an empty store.
+
 ![cargo-hauler dashboard kache timing panel](docs/media/dashboard-kache.png)
 
 ## Install
@@ -470,7 +542,8 @@ Per-host notes and hook timeouts are in [docs/install.md](docs/install.md).
 | --- | --- | --- |
 | `CARGO_HAULER_STATE_DIR` | Per-user cache directory | Unix socket or Windows named pipe source, SQLite ledger, daemon log, pid lock, `hook-state.json`, `hook-events.jsonl`, and the per-ticket output logs under `tickets/`. 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`. 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_MAX_CONCURRENT` | cores ÷ 8, clamped to 5–16 | Global admission permits for Cargo processes across all lanes; an integer >= 1. |
+| `CARGO_HAULER_OVERLAP_EXECUTION` | `1` | Hand a lane to its next request once a `test`/`nextest`/`bench`/`run` leader reports its build finished, overlapping the next compile with the leader's execution phase. `0` keeps a lane strictly one process at a time. |
 | `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_JOBSERVER` | `auto` | Machine-wide fifo jobserver for daemon-spawned cargo: `auto` arms it only when the host `make` is 4.4+ (or absent) because older makes reject `--jobserver-auth=fifo:` in build scripts; `fifo` forces it on, `off` disables it (per-run `CARGO_BUILD_JOBS` grants apply instead). |
 | `CARGO_HAULER_LOAD_THRESHOLD` | Disabled | Per-core one-minute load threshold for deferring new admissions. |
@@ -529,9 +602,14 @@ unset, the daemon reads kache's configured local store from
   document names the one in use (`state dir …` in the header; `stateRoot` in
   `--json`), so a `CARGO_HAULER_STATE_DIR` change is visible on the next
   command rather than discovered from an empty ledger.
-- 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.
+- Test execution is never shared by coverage: a `test`, `nextest`, or `bench`
+  that runs tests attaches only by identity or batch folding. Only a
+  compile-only `test --no-run` / `bench --no-run` rides a running `test` /
+  `bench`, and it is released by the leader's build alone. Folded `test` and
+  `nextest` requests receive the composite output, and a composite may run
+  more than one participant asked for (another package, another name
+  filter); its failure is inherited only by participants that asked for
+  everything it ran, the rest rerun alone.
 - 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
@@ -550,9 +628,9 @@ unset, the daemon reads kache's configured local store from
 <summary><strong>How the app is built</strong> — agent-bundle application structure, testing, and development (click to expand)</summary>
 
 The plugin is an [agent-bundle](https://github.com/ScriptedAlchemy/agent-bundle)
-application: six MCP tools, a routed CLI, four hook routes, two skills, and a
-browser dashboard, all rendered from one component library through one shared
-layout. This section is for contributors; using cargo-hauler needs none of it.
+application: six MCP tools, a routed CLI, two hook routes plus two declared
+shell hooks, two skills, and a browser dashboard, all rendered from one
+component library through one shared layout. This section is for contributors; using cargo-hauler needs none of it.
 
 ### Application structure
 
@@ -569,7 +647,8 @@ src/
   mcp/hauler/tools/*.tsx        hauler_status, _log, _last, _await, _result, _request
   mcp/hauler/apps/dashboard.tsx the MCP App (ui://cargo-hauler/dashboard.html)
   cli/*.tsx, cli/daemon.ts      the routed `cargo-hauler` CLI, same components
-  events/{session/start,tool/before,tool/after,stop}.tsx   hook routes
+  events/{session/start,stop}.tsx   rendered hook routes
+  hooks/fast-path/              the declared tool/before and tool/after shell hooks
   skills/cargo-hauler/SKILL.md, skills/hauler-dashboard/SKILL.tsx
   scripts/hauler.ts             the `hauler` process entry hooks rewrite cargo to
   daemon/, client/, hooks/, shim/, lib/   the broker and its libraries
@@ -600,6 +679,24 @@ through one layout, the way a page framework's `layout.tsx` wraps every page:
 
 Event routes are host protocol responses and are never wrapped.
 
+#### The shell hooks (`src/hooks/fast-path/`)
+
+`tool/before` and `tool/after` are not rendered routes. They are declared in
+`agent-bundle.config.ts` under `hooks` as handler modules
+(`shell-before.ts`, `shell-after.ts`), which the framework compiles into
+standalone entries — `hooks/before-tool-shell-before-<hash>.mjs`,
+`hooks/after-tool-shell-after-<hash>.mjs` — that carry no React, no Flight
+worker, and no Effect. Each entry decides on the raw command first
+(`tokens.ts`; `session-ping.ts` for the completion ping) and reaches the
+rewrite (`before-shell.ts`) or the telemetry and notification code
+(`after-shell.ts`) through a deliberate dynamic `import()`, the one place in
+the codebase that imports lazily. The handler contract has no `allow`
+outcome, so a fully brokered rewrite writes the host's own allow shape
+(`allow-output.ts`) instead of `continue` + `updatedInput`, which would make
+the host prompt for the rewrite. Everything else — `continue`, `deny` with a
+reason, `additionalContext` — goes through the generated wrapper's
+projection.
+
 #### The daemon provider (`src/providers/hauler-daemon.ts`)
 
 One request-context provider mounts `providers.haulerDaemon` for every tool,
@@ -683,9 +780,9 @@ 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, 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) |
+| `hooks.beforeTool` (`src/hooks/fast-path/shell-before.ts`) | shell tool about to run | `continue` without loading anything for a non-cargo command; otherwise 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 |
+| `hooks.afterTool` (`src/hooks/fast-path/shell-after.ts`) | shell tool finished | one bounded completion ping per call; injects finished background-ticket results once per session |
 
 #### Skills
 
@@ -703,6 +800,18 @@ render MCP Apps. It shows contention and admission, in-flight and queued
 work, metrics windows, optional kache data, lanes, and history, with a live
 output drawer per ticket.
 
+Each metrics window also reports queue wait against run time for leaders,
+with the wait split by cause: *lane-bound* (a same-lane leader was still
+compiling — before its `Finished` line or exit), *permit-bound* (every
+admission permit was held and no same-lane compile was to blame), and *other*
+(admission holds, `--after` prerequisites, scheduling latency). The
+classification is a pure sweep over ledger rows (`src/daemon/wait-split.ts`)
+run once per status refresh against the daemon's current permit count, which
+the tile states; runs admitted under an earlier cap are classified against
+today's. With `buildFinishedAtMs` on the row, the by-command split adds
+compile vs execution time for test/run/bench leaders and the window reports
+the lane time the execution-phase hand-back released.
+
 ### Testing
 
 ```sh
@@ -714,7 +823,7 @@ artifact build, at the harness proof levels:
 
 | Level | Suite | What it proves |
 | --- | --- | --- |
-| route-unit | `routes`, `layout`, `streaming`, `events` | documents, shell metadata, Suspense fallbacks and settled values, lineage attribution, event decisions |
+| route-unit | `routes`, `layout`, `streaming`, `events` | documents, shell metadata, Suspense fallbacks and settled values, lineage attribution, event decisions (the shell hooks are unit-tested in `tests/hook-fast-path.test.ts` and against their compiled entries in `tests/hooks-simulate.test.ts`) |
 | cli-dispatch | `cli-dispatch`, `layout` | argv through the routed CLI shell; Markdown wrapped by the shell, `--json` bare |
 | script-dispatch | `script-dispatch` | the `hauler` entry through its `main` envelope as its own process |
 | mcp-in-memory | `mcp-surface`, `layout` | tool names, `outputSchema`, the dashboard resource link, `_meta.hauler`, and a live fixture broker over the in-memory transport |

package/artifact/agent-bundle.hooks.json

@@ -1 +1 @@
-{"hooks":[{"event":"sessionStart","id":"hook:event-route:session-start","name":"event-route-session-start","path":"claude/hooks/event-route-session-start.mjs","target":"claude","timeout":5},{"event":"stop","id":"hook:event-route:stop","name":"event-route-stop","path":"claude/hooks/event-route-stop.mjs","target":"claude","timeout":900},{"event":"afterTool","id":"hook:event-route:tool-after","name":"event-route-tool-after","path":"claude/hooks/event-route-tool-after.mjs","target":"claude","timeout":10},{"event":"beforeTool","id":"hook:event-route:tool-before","name":"event-route-tool-before","path":"claude/hooks/event-route-tool-before.mjs","target":"claude","timeout":10},{"event":"sessionStart","id":"hook:event-route:session-start","name":"event-route-session-start","path":"codex/hooks/event-route-session-start.mjs","target":"codex","timeout":5},{"event":"stop","id":"hook:event-route:stop","name":"event-route-stop","path":"codex/hooks/event-route-stop.mjs","target":"codex","timeout":900},{"event":"afterTool","id":"hook:event-route:tool-after","name":"event-route-tool-after","path":"codex/hooks/event-route-tool-after.mjs","target":"codex","timeout":10},{"event":"beforeTool","id":"hook:event-route:tool-before","name":"event-route-tool-before","path":"codex/hooks/event-route-tool-before.mjs","target":"codex","timeout":10},{"event":"sessionStart","id":"hook:event-route:session-start","name":"event-route-session-start","path":"cursor/hooks/event-route-session-start.mjs","target":"cursor","timeout":5},{"event":"stop","id":"hook:event-route:stop","name":"event-route-stop","path":"cursor/hooks/event-route-stop.mjs","target":"cursor","timeout":900},{"event":"afterTool","id":"hook:event-route:tool-after","name":"event-route-tool-after","path":"cursor/hooks/event-route-tool-after.mjs","target":"cursor","timeout":10},{"event":"beforeTool","id":"hook:event-route:tool-before","name":"event-route-tool-before","path":"cursor/hooks/event-route-tool-before.mjs","target":"cursor","timeout":10}]}
+{"hooks":[{"event":"afterTool","id":"hook:after-tool:shell-after:264de610","name":"after-tool-shell-after-264de610","path":"claude/hooks/after-tool-shell-after-264de610.mjs","target":"claude","timeout":10},{"event":"beforeTool","id":"hook:before-tool:shell-before:9212219e","name":"before-tool-shell-before-9212219e","path":"claude/hooks/before-tool-shell-before-9212219e.mjs","target":"claude","timeout":10},{"event":"sessionStart","id":"hook:event-route:session-start","name":"event-route-session-start","path":"claude/hooks/event-route-session-start.mjs","target":"claude","timeout":5},{"event":"stop","id":"hook:event-route:stop","name":"event-route-stop","path":"claude/hooks/event-route-stop.mjs","target":"claude","timeout":900},{"event":"afterTool","id":"hook:after-tool:shell-after:264de610","name":"after-tool-shell-after-264de610","path":"codex/hooks/after-tool-shell-after-264de610.mjs","target":"codex","timeout":10},{"event":"beforeTool","id":"hook:before-tool:shell-before:9212219e","name":"before-tool-shell-before-9212219e","path":"codex/hooks/before-tool-shell-before-9212219e.mjs","target":"codex","timeout":10},{"event":"sessionStart","id":"hook:event-route:session-start","name":"event-route-session-start","path":"codex/hooks/event-route-session-start.mjs","target":"codex","timeout":5},{"event":"stop","id":"hook:event-route:stop","name":"event-route-stop","path":"codex/hooks/event-route-stop.mjs","target":"codex","timeout":900},{"event":"afterTool","id":"hook:after-tool:shell-after:264de610","name":"after-tool-shell-after-264de610","path":"cursor/hooks/after-tool-shell-after-264de610.mjs","target":"cursor","timeout":10},{"event":"beforeTool","id":"hook:before-tool:shell-before:9212219e","name":"before-tool-shell-before-9212219e","path":"cursor/hooks/before-tool-shell-before-9212219e.mjs","target":"cursor","timeout":10},{"event":"sessionStart","id":"hook:event-route:session-start","name":"event-route-session-start","path":"cursor/hooks/event-route-session-start.mjs","target":"cursor","timeout":5},{"event":"stop","id":"hook:event-route:stop","name":"event-route-stop","path":"cursor/hooks/event-route-stop.mjs","target":"cursor","timeout":900}]}