@mu-crew/muzzle 0.1.2 → 0.2.0

package/bin/muzzle

@@ -34,8 +34,12 @@ try {
 if (typeof process.execve === "function") {
   try {
     process.execve(binary, [binary, ...process.argv.slice(2)], process.env);
-  } catch {
-    // fall through to spawn, which reports the error
+  } catch (error) {
+    // Say so: the spawn below brings back the group-kill leak (D16), and
+    // silently is how it went unnoticed. Spawn then reports any real error.
+    console.error(
+      `muzzle: execve failed (${error.code ?? error.message}), falling back to spawn: a group kill may leak the job`,
+    );
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/muzzle",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Per-host admission for heavy commands, with a run log that tunes itself",
   "license": "MIT",
   "repository": {
@@ -42,8 +42,8 @@
     }
   },
   "optionalDependencies": {
-    "@mu-crew/muzzle-linux-x64": "0.1.2",
-    "@mu-crew/muzzle-linux-arm64": "0.1.2",
-    "@mu-crew/muzzle-darwin-arm64": "0.1.2"
+    "@mu-crew/muzzle-linux-x64": "0.2.0",
+    "@mu-crew/muzzle-linux-arm64": "0.2.0",
+    "@mu-crew/muzzle-darwin-arm64": "0.2.0"
   }
 }

package/skills/muzzle/SKILL.md

@@ -60,6 +60,14 @@ muzzle run --rule gate --run-timeout 900 -- contrib/fast-gate
   `MUZZLE_SLOTS` from the claim and overwrites any it inherits. Drop
   hand-set caps from the command; an assignment inside the command string
   still wins.
+- **Wrap a script as a whole.** muzzle can't see inside a script, so a
+  script you write that runs builds or tests (`./check.sh`, `python3
+  /tmp/x.py`, a heredoc) matches no rule and runs unclaimed. Wrap the
+  whole script under the rule of the heaviest thing it runs:
+  `muzzle run --rule cargo-test -- ./check.sh`, or
+  `muzzle run --rule cargo-test -- bash -c 'cargo build && cargo test'`.
+  Don't move a gate into a script to skip the queue: the machine still
+  pays for it, and every other agent's gate slows down.
 - A background launch (`(gate > log 2>&1 &)`) keeps its slots: `muzzle run`
   returns at once and a keeper holds the claim until the job exits. Polling
   the log is fine. A poll that repeats the gate's command line would claim a
@@ -98,6 +106,30 @@ muzzle run --rule gate --run-timeout 900 -- contrib/fast-gate
   running in the container. Its slots stay held until it exits, so find
   and kill it there.
 
+## The config
+
+`~/.config/muzzle/config.toml` holds global `[[rule]]` entries. A
+`[path."<dir>"]` table changes rules for the repos under a directory, and
+`include = ["machine.toml"]` merges a per-machine file. Example:
+
+```toml
+include = ["machine.toml"]
+
+[[rule]]
+name  = "cargo-test"
+match = '\bcargo (test|nextest|clippy|build)\b'
+slots = 3
+
+[path."~/hacking/crew"]
+[[path."~/hacking/crew".rule]]
+name  = "cargo-test"
+slots = 2              # reweight only; match is inherited
+```
+
+There is no discovery mode. To set muzzle up on a machine, write the rules
+from the heavy commands you know, check them with `muzzle match`, and tune
+from the run log: [recipes/tune.md](recipes/tune.md).
+
 ## Recipes
 
 - Changing a rule's weight or pattern, reading `muzzle report`:

package/skills/muzzle/recipes/tune.md

@@ -8,6 +8,19 @@ under, so `report --compare` can split by them later.
 Run on the host whose config you are changing. `runs.jsonl` is local machine
 state: read it here, and never publish it.
 
+## 0. A new machine: write the config, then trial it
+
+There is no discovery mode. Start from what you know:
+
+1. List the heavy commands agents run here: gates, `cargo test`, `npm test`,
+   e2e suites. museum helps (step 2).
+2. Write a rule for each, in the shared file, with a weight from the
+   command's usual job cap (`CARGO_BUILD_JOBS=4` means 4). Check each
+   pattern with `muzzle match -- 'contrib/gate --full'`.
+3. Put this machine's budget and weights in an untracked `machine.toml` next
+   to it (layout in step 3), so one shared file serves every machine.
+4. Run real work for a day or two, then start the loop at step 1.
+
 ## 1. Read the report, machine figures first
 
 ```sh
@@ -22,6 +35,7 @@ Read the machine section before the rows:
 | CPU efficiency (low) | claims are bigger than the jobs use: weights too big |
 | utilisation near 100% while the machine's CPU stays low | the budget is saturated but the cores aren't: the reserve is too big |
 | queue non-empty | how often anyone waited at all. Near 0% means the weights cost nothing yet |
+| unclaimed load (cores) | load that no claim accounts for: `load1 − held` at admission. High means heavy work runs outside muzzle. Find the unmatched heavy commands (step 2) and add rules, or raise `reserve` to leave room for them. It is rough: the load average lags, and on Linux it counts I/O wait |
 
 Then the rows. `suggest` names its evidence and carries a tag:
 
@@ -38,6 +52,24 @@ Then the rows. `suggest` names its evidence and carries a tag:
 Narrow to one rule with `--rule NAME`, or to a period with `--since D`
 and `--until D` (`now`, `7d`, `12h`, `30m`, `YYYY-MM-DD`, or RFC 3339).
 
+### Per repo
+
+One rule can behave very differently per repo: a `cargo test` that takes
+1 s in one repo can take 30 s in another. Split the rows by repo:
+
+```sh
+muzzle report --by repo --since 7d --rule cargo-test
+```
+
+Each row is one (rule, repo); `(none)` is runs outside any repo. The
+`now` column is the slots the **current** config gives that repo, and
+where they come from: `now 3 (from [path."~/hacking/crew"] in
+machine.toml)`. When the runs used a different weight, it adds `; runs used
+4`. `not in the current config here` means the rule is off or absent for
+that repo now, so there is no suggestion. When suggestions for one rule
+differ a lot between repos, give the outliers a path table (step 3).
+`--by repo` can't be combined with `--compare`.
+
 **Done when** you have written down, for the rule you will change, its
 current slots, run p50/p90, cores p50/p90 and the suggestion.
 
@@ -54,11 +86,53 @@ Check a candidate against the live config with
 `muzzle match -- 'contrib/gate --full'`. It prints the rule, or `no rule
 matches`.
 
+Heavy work inside a script (`./run.sh`, `python3 /tmp/x.py`) matches no
+rule, because muzzle only sees the script's name. A high unclaimed load
+with no unmatched commands in museum usually means this. The fix is
+wrapping such scripts with `muzzle run --rule cargo-test -- ./run.sh`
+(SKILL.md), not a rule for every script name.
+
 ## 3. Edit the config
 
 `~/.config/muzzle/config.toml`. Change one rule per round, so the next
 report shows what that change did.
 
+Where a change goes:
+
+```toml
+# ~/.config/muzzle/config.toml: shared, tracked in dotfiles
+include = ["machine.toml"]
+
+[[rule]]
+name  = "cargo-test"
+match = '\bcargo (test|nextest|clippy|build)\b'
+slots = 3
+
+[path."~/hacking/swayward-wm"]          # every repo under here, every worktree
+[[path."~/hacking/swayward-wm".rule]]
+name  = "cargo-test"
+slots = 6                               # reweight only; match inherited
+```
+
+```toml
+# ~/.config/muzzle/machine.toml: this machine only, untracked
+reserve = 2
+[[rule]]
+name  = "cargo-test"
+slots = 4                               # this machine's global weight
+```
+
+- **A weight for every repo on this machine**: the global rule in
+  `machine.toml`.
+- **A weight for some repos**: a `[path."<dir>"]` table with just `name`
+  and `slots`. The key is a directory; it covers every repo under it and
+  all their worktrees. A nearer table wins over a further one.
+- **A rule that should not fire in one repo**: `enabled = false` in its
+  table.
+- After the edit, `muzzle match --json --cwd ~/hacking/swayward-wm/swayward
+  -- 'cargo test'` shows the slots there and `slots_from`, the file and
+  table they came from.
+
 - **Weights**: set `slots` to the suggestion. For an `experiment`, that
   is the `try N` value, and step 5 decides whether it stays.
 - **New rules**: give each a `name`. The name is the label in reports and
@@ -83,7 +157,9 @@ Check the edit loads, and note the new hash:
 muzzle doctor
 ```
 
-A bad config exits 2 and names the key.
+A bad config exits 2 and names the key and the file. `doctor` also lists
+each include as `found` or `not found`: a typo in an include path is
+skipped silently otherwise.
 
 **Hand-wrapped calls carry their own weight.** A `--slots` on
 `muzzle run` overrides the config, so editing the config changes nothing for briefs,
@@ -117,6 +193,10 @@ After a few days, or at least 5 clean runs at the new weight:
 muzzle report --compare 2026-11-01..2026-11-03 2026-11-04..now --rule cargo-test
 ```
 
+For a path-table change, compare per repo instead: run
+`muzzle report --by repo --since 2026-11-04 --rule cargo-test` and check
+the repo's row against the one you wrote down in step 1.
+
 The output shows both periods, split by config hash when it changed inside
 one, then an `A -> C` table of deltas. An experiment reads `confirmed` when
 run p50 fell, `rejected` when it didn't.