@mu-crew/muzzle 0.1.1 → 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/extension/muzzle.ts

@@ -7,6 +7,12 @@
 // tool_result: read the report, append `muzzle: waited Ws for N slots, ran
 // Rs` and a `muzzle` custom entry with the same numbers (D26).
 //
+// One copy per pi process: the pi package and `-e <path>` can both load this
+// file, and two copies would each wrap the call (the CLI also refuses to wrap
+// a command that already runs muzzle, D22). The first copy to load claims
+// GUARD on globalThis; later copies register nothing. The claim is released
+// on session_shutdown, so /reload and session replacement load it again.
+//
 // Nothing here may block a call: a missing binary or a failing wrap leaves
 // the call as it is. A throwing tool_call handler blocks the tool in pi, so
 // every path is caught.
@@ -134,6 +140,9 @@ function wrap(bin: string, command: string, cwd: string, timeout?: number): Prom
   });
 }
 
+/** The process-wide claim; registry-global so separate module copies share it. */
+export const GUARD = Symbol.for("@mu-crew/muzzle/extension");
+
 export interface Deps {
   findBinary?: () => string | null;
   tmpRoot?: string;
@@ -142,6 +151,10 @@ export interface Deps {
 export function createExtension(deps: Deps = {}) {
   const findBinary = deps.findBinary ?? (() => findMuzzle());
   return function (pi: ExtensionAPI) {
+    const g = globalThis as Record<symbol, unknown>;
+    if (g[GUARD] !== undefined) return;
+    const claim = {};
+    g[GUARD] = claim;
     let bin: string | null | undefined;
     let reportDir: string | undefined;
     const pending = new Map<string, string>();
@@ -167,6 +180,8 @@ export function createExtension(deps: Deps = {}) {
           if (bin === null) warn(ctx, "muzzle not found: bash calls run unwrapped");
         }
         if (bin === null) return;
+        // Belt and braces for the guard: our own rewrite is never rewritten.
+        if (input.command.startsWith(`${shellQuote(bin)} run `)) return;
         const timeout = typeof input.timeout === "number" ? input.timeout : undefined;
         const wrapped = await wrap(bin, input.command, ctx.cwd, timeout);
         if (wrapWarned) {
@@ -213,6 +228,7 @@ export function createExtension(deps: Deps = {}) {
     });
 
     pi.on("session_shutdown", async () => {
+      if (g[GUARD] === claim) delete g[GUARD];
       if (reportDir) rmSync(reportDir, { recursive: true, force: true });
       reportDir = undefined;
       pending.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-crew/muzzle",
-  "version": "0.1.1",
+  "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.1",
-    "@mu-crew/muzzle-linux-arm64": "0.1.1",
-    "@mu-crew/muzzle-darwin-arm64": "0.1.1"
+    "@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

@@ -53,13 +53,21 @@ muzzle run --rule gate --run-timeout 900 -- contrib/fast-gate
 - **`timeout` goes inside `muzzle run`, never outside it.** An outer
   `timeout` counts the queue wait and kills the gate before it starts. Use
   `--run-timeout S`, which counts from admission and exits 124.
-- In pi, a command that starts with `muzzle ` is left alone by the
-  extension, so pi's own bash `timeout` still counts the wait. Give a
+- In pi, a command that already runs muzzle (`muzzle run …`, by any
+  path) is left alone by the extension, so pi's own bash `timeout` still counts the wait. Give a
   hand-wrapped call no pi timeout, and put the limit in `--run-timeout`.
 - muzzle sets `CARGO_BUILD_JOBS`, `RUST_TEST_THREADS`, `MAKEFLAGS` and
   `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.