@roulabs/mx 1.7.1 → 1.11.0

package/bin/mx.js

@@ -2,7 +2,7 @@
 
 // src/main.ts
 import { readFileSync as readFileSync2 } from "fs";
-import * as path8 from "path";
+import * as path9 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // ../../packages/core/src/errors.ts
@@ -195,6 +195,7 @@ function updateRuntime(root, templatesDir2) {
 
 // ../../packages/core/src/repos.ts
 import * as fs5 from "fs";
+import * as path4 from "path";
 
 // ../../packages/core/src/git.ts
 import { execFileSync } from "child_process";
@@ -284,6 +285,93 @@ function repoInfo(root, name) {
     worktreesInWorks: usedBy
   };
 }
+function originDefaultBranch(rp) {
+  const out = gitQuiet(["-C", rp, "symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+  if (!out) return null;
+  const m = out.match(/^origin\/(.+)$/);
+  return m ? m[1] : null;
+}
+function currentBranchOrNull(rp) {
+  const out = gitQuiet(["-C", rp, "symbolic-ref", "--short", "-q", "HEAD"]);
+  return out || null;
+}
+function statusCounts(rp) {
+  const out = gitQuiet(["-C", rp, "status", "--porcelain"]);
+  if (!out) return [0, 0];
+  let uncommitted = 0;
+  let untracked = 0;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("??")) untracked++;
+    else if (line.length > 0) uncommitted++;
+  }
+  return [uncommitted, untracked];
+}
+function aheadBehind(rp, branch) {
+  if (!branch) return [null, null];
+  const upstream = `refs/remotes/origin/${branch}`;
+  const upstreamExists = gitQuiet(["-C", rp, "rev-parse", "--verify", upstream]);
+  if (!upstreamExists) return [null, null];
+  const out = gitQuiet(["-C", rp, "rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+  if (!out) return [null, null];
+  const [aheadStr, behindStr] = out.split(/\s+/);
+  return [Number(aheadStr), Number(behindStr)];
+}
+function lastFetched(rp) {
+  const fh = path4.join(rp, ".git", "FETCH_HEAD");
+  if (!exists(fh)) return null;
+  return fs5.statSync(fh).mtime.toISOString();
+}
+function repoHealth(root, name) {
+  const rp = repoPath(root, name);
+  if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
+  const defaultBranch = originDefaultBranch(rp);
+  const current = currentBranchOrNull(rp);
+  const isOnDefault = current !== null && defaultBranch !== null && current === defaultBranch;
+  const [uncommittedChanges, untrackedFiles] = statusCounts(rp);
+  const [aheadOfOrigin, behindOfOrigin] = aheadBehind(rp, current);
+  const lastFetchedAt = lastFetched(rp);
+  const worktreesInWorks = listWorkNames(root).filter(
+    (w) => findWorktree(readWork(root, w), name)
+  );
+  const issues = [];
+  if (current === null) {
+    issues.push("HEAD is detached");
+  } else if (defaultBranch && !isOnDefault) {
+    issues.push(`on ${current} (default: ${defaultBranch})`);
+  }
+  if (uncommittedChanges > 0) {
+    issues.push(
+      `${uncommittedChanges} uncommitted change${uncommittedChanges === 1 ? "" : "s"}`
+    );
+  }
+  if (untrackedFiles > 0) {
+    issues.push(`${untrackedFiles} untracked file${untrackedFiles === 1 ? "" : "s"}`);
+  }
+  if (behindOfOrigin !== null && behindOfOrigin > 0) {
+    issues.push(`${behindOfOrigin} commit${behindOfOrigin === 1 ? "" : "s"} behind origin/${current}`);
+  }
+  if (aheadOfOrigin !== null && aheadOfOrigin > 0) {
+    issues.push(`${aheadOfOrigin} commit${aheadOfOrigin === 1 ? "" : "s"} ahead of origin/${current}`);
+  }
+  return {
+    name,
+    path: rp,
+    defaultBranch,
+    currentBranch: current,
+    isOnDefault,
+    uncommittedChanges,
+    untrackedFiles,
+    aheadOfOrigin,
+    behindOfOrigin,
+    lastFetchedAt,
+    worktreesInWorks,
+    healthy: issues.length === 0,
+    issues
+  };
+}
+function listRepoHealth(root) {
+  return listRepoNames(root).map((name) => repoHealth(root, name));
+}
 function repoRemove(root, name) {
   const rp = repoPath(root, name);
   if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
@@ -300,7 +388,7 @@ function repoRemove(root, name) {
 
 // ../../packages/core/src/works.ts
 import * as fs6 from "fs";
-import * as path4 from "path";
+import * as path5 from "path";
 function addFolderToWorkspace(root, name, repo) {
   const file = workspaceFile(root, name);
   const ws = exists(file) ? readJson(file) : { folders: [], settings: {} };
@@ -364,7 +452,7 @@ function worktreeAdd(root, name, repo, opts = {}) {
     throw new MxError(`work "${name}" already has worktree for ${repo}`, "EXISTS");
   }
   const branch = opts.branch || name;
-  const dest = path4.join(workDir(root, name), repo);
+  const dest = path5.join(workDir(root, name), repo);
   if (branchExists(rp, branch)) {
     git(["-C", rp, "worktree", "add", dest, branch]);
   } else {
@@ -391,7 +479,7 @@ function worktreeRemove(root, name, repo) {
   const work = readWork(root, name);
   const wt = findWorktree(work, repo);
   if (!wt) throw new MxError(`work "${name}" has no worktree for ${repo}`, "NO_WORKTREE");
-  const dest = path4.join(workDir(root, name), repo);
+  const dest = path5.join(workDir(root, name), repo);
   if (exists(dest) && isDirty(dest)) {
     throw new MxError(`worktree ${repo} has uncommitted changes \u2014 commit or discard them first`, "DIRTY");
   }
@@ -411,7 +499,7 @@ function workDestroy(root, name, opts = {}) {
   const work = readWork(root, name);
   const dirty = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path4.join(workDir(root, name), wt.repo);
+    const dest = path5.join(workDir(root, name), wt.repo);
     if (exists(dest) && isDirty(dest)) dirty.push(wt.repo);
   }
   if (dirty.length) {
@@ -422,7 +510,7 @@ function workDestroy(root, name, opts = {}) {
   }
   const removed = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path4.join(workDir(root, name), wt.repo);
+    const dest = path5.join(workDir(root, name), wt.repo);
     if (exists(dest)) git(["-C", repoPath(root, wt.repo), "worktree", "remove", dest]);
     removed.push(wt.repo);
   }
@@ -436,7 +524,7 @@ function archiveWork(root, name) {
   }
   const dirty = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path4.join(workDir(root, name), wt.repo);
+    const dest = path5.join(workDir(root, name), wt.repo);
     if (exists(dest) && isDirty(dest)) dirty.push(wt.repo);
   }
   if (dirty.length) {
@@ -447,7 +535,7 @@ function archiveWork(root, name) {
   }
   const removed = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path4.join(workDir(root, name), wt.repo);
+    const dest = path5.join(workDir(root, name), wt.repo);
     if (exists(dest)) git(["-C", repoPath(root, wt.repo), "worktree", "remove", dest]);
     removed.push(wt.repo);
   }
@@ -486,7 +574,7 @@ function unarchiveWork(root, name, overrides = {}) {
   }
   const restored = [];
   for (const d of desired) {
-    const dest = path4.join(workDir(root, name), d.repo);
+    const dest = path5.join(workDir(root, name), d.repo);
     git(["-C", repoPath(root, d.repo), "worktree", "add", dest, d.branch]);
     addFolderToWorkspace(root, name, d.repo);
     restored.push({ repo: d.repo, branch: d.branch, path: dest, ports: d.ports });
@@ -566,9 +654,9 @@ function portList(root, name) {
 }
 
 // ../../packages/core/src/status.ts
-import * as path5 from "path";
+import * as path6 from "path";
 function countContextEntries(root) {
-  const indexPath = path5.join(root, "context", "INDEX.json");
+  const indexPath = path6.join(root, "context", "INDEX.json");
   if (!exists(indexPath)) return 0;
   try {
     const data = readJson(indexPath);
@@ -577,12 +665,16 @@ function countContextEntries(root) {
     return 0;
   }
 }
-function statusRuntime(root) {
+function statusRuntime(root, opts = {}) {
+  const all = listWorksInfo(root, { includeArchived: true });
+  const archivedWorksCount = all.filter((w) => w.isArchived === true).length;
+  const works = opts.onlyArchived ? all.filter((w) => w.isArchived === true) : opts.includeArchived ? all : all.filter((w) => w.isArchived !== true);
   return {
     runtime: root,
     context: { entries: countContextEntries(root) },
     repos: listReposInfo(root),
-    works: listWorksInfo(root, { includeArchived: true })
+    works,
+    archivedWorksCount
   };
 }
 
@@ -602,6 +694,8 @@ function parseArgs(argv) {
     help: false,
     version: false,
     force: false,
+    yes: false,
+    all: false,
     archived: false
   };
   for (let i = 0; i < argv.length; i++) {
@@ -614,6 +708,10 @@ function parseArgs(argv) {
       flags.version = true;
     } else if (a === "--force") {
       flags.force = true;
+    } else if (a === "--yes" || a === "-y") {
+      flags.yes = true;
+    } else if (a === "--all") {
+      flags.all = true;
     } else if (a === "--archived") {
       flags.archived = true;
     } else if (a.startsWith("--") && a.includes("=")) {
@@ -631,6 +729,7 @@ function parseArgs(argv) {
 }
 
 // src/output.ts
+import { spawnSync } from "child_process";
 var USE_STYLE = process.stdout.isTTY && !process.env.NO_COLOR;
 function wrap(s, code) {
   return USE_STYLE ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -647,6 +746,18 @@ function check() {
 function warn() {
   return "\u26A0";
 }
+function confirmYesNo(prompt) {
+  if (!process.stdin.isTTY) return false;
+  process.stdout.write(prompt);
+  const result = spawnSync(
+    "/bin/sh",
+    ["-c", `IFS= read -r REPLY && printf '%s' "$REPLY"`],
+    { stdio: ["inherit", "pipe", "inherit"], encoding: "utf8" }
+  );
+  if (result.status !== 0 || result.signal) return false;
+  const answer = (result.stdout ?? "").trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
 var porcelain = false;
 function setPorcelain(value) {
   porcelain = value;
@@ -679,7 +790,7 @@ var HELP = `mx \u2014 control panel for the mx runtime
 
 Global:
   mx init [path]                         scaffold/adopt a runtime (default ~/mx)
-  mx status [--porcelain]                show runtime, repos, works, ports  (aliases: mx s, mx st)
+  mx status [--all] [--porcelain]        show runtime, repos, works, ports (active only by default; --all to include archived; aliases: mx s, mx st)
   mx update                              re-sync runtime from current templates + backfill structural scaffolding
   mx help | version
 
@@ -688,11 +799,13 @@ Repos (pristine clones):
   mx repo ls [--porcelain]
   mx repo -n <name> fetch                git fetch (+ ff current branch)
   mx repo -n <name> info [--porcelain]
+  mx repo health [--porcelain]           pure-local health summary for every pristine clone
+  mx repo -n <name> health [--porcelain] detailed health for one pristine clone
   mx repo -n <name> rm                   refuses if any work uses it
 
 Works (features):
   mx work new <name> [--description <t>]                creates folder + empty work.json + sessions/
-  mx work ls [--archived] [--porcelain]                 default: all works (archived marked); --archived filters to archived only
+  mx work ls [--all|--archived] [--porcelain]           default: active only; --all includes archived; --archived shows archived only
   mx work -n <name> info [--porcelain]
   mx work -n <name> path                                print the work folder path (cd "$(mx work -n <name> path)")
   mx work -n <name> describe <text>
@@ -702,7 +815,7 @@ Works (features):
   mx work -n <name> port set <repo> <service> [<port>]  auto-picks a free port if omitted
   mx work -n <name> port unset <repo> <service>
   mx work -n <name> port ls [--porcelain]
-  mx work -n <name> archive                             removes worktrees; keeps folder + work.json + sessions; recoverable
+  mx work -n <name> archive [--yes|-y]                  removes worktrees; keeps folder + work.json + sessions; prompts for confirmation (use --yes to skip)
   mx work -n <name> unarchive [<repo>=<branch>...]      re-creates worktrees from work.json; override per-repo branch if recorded one is missing
   mx work -n <name> destroy --force                     PERMANENT: deletes the work folder including session summaries (branches kept). Prefer archive.
 
@@ -714,20 +827,20 @@ Runtime discovery: --runtime <path>  ->  $MX_RUNTIME  ->  default ~/mx.
 `;
 
 // src/commands/global.ts
-import * as path7 from "path";
+import * as path8 from "path";
 
 // src/paths.ts
-import * as path6 from "path";
+import * as path7 from "path";
 import { fileURLToPath } from "url";
 function templatesDir() {
   if (process.env.MX_TEMPLATES_DIR) return process.env.MX_TEMPLATES_DIR;
-  const here = path6.dirname(fileURLToPath(import.meta.url));
-  return path6.join(here, "..", "templates");
+  const here = path7.dirname(fileURLToPath(import.meta.url));
+  return path7.join(here, "..", "templates");
 }
 
 // src/commands/global.ts
 function runtimeEnvHint(runtime) {
-  const envRuntime = process.env.MX_RUNTIME ? path7.resolve(process.env.MX_RUNTIME) : null;
+  const envRuntime = process.env.MX_RUNTIME ? path8.resolve(process.env.MX_RUNTIME) : null;
   if (envRuntime === runtime) {
     return ["", `${dim("$MX_RUNTIME already points here \u2014 you're set.")}`];
   }
@@ -757,7 +870,7 @@ function runGlobal(positionals, flags) {
     }
     case "status": {
       const root = requireRuntime({ runtime: flags.runtime });
-      const data = statusRuntime(root);
+      const data = statusRuntime(root, { includeArchived: flags.all });
       emit(() => renderStatus(data), data);
       return;
     }
@@ -794,16 +907,18 @@ function renderStatus(data) {
     }
   }
   console.log();
-  const active = data.works.filter((w) => w.isArchived !== true);
-  const archived = data.works.filter((w) => w.isArchived === true);
-  const worksCount = archived.length > 0 ? dim(`(${active.length} active, ${archived.length} archived)`) : dim(`(${data.works.length})`);
+  const visibleArchived = data.works.filter((w) => w.isArchived === true);
+  const visibleActive = data.works.filter((w) => w.isArchived !== true);
+  const hiddenArchived = data.archivedWorksCount - visibleArchived.length;
+  const worksCount = data.archivedWorksCount > 0 ? dim(`(${visibleActive.length} active, ${data.archivedWorksCount} archived${hiddenArchived > 0 ? ` \u2014 pass --all to show` : ""})`) : dim(`(${data.works.length})`);
   console.log(`  ${bold("works")}  ${worksCount}`);
   if (data.works.length === 0) {
-    console.log(`    ${dim("none yet \u2014 `mx work new <name>`")}`);
+    const empty = hiddenArchived > 0 ? `${hiddenArchived} archived hidden \u2014 pass --all to show` : "none yet \u2014 `mx work new <name>`";
+    console.log(`    ${dim(empty)}`);
     console.log();
     return;
   }
-  const ordered = [...active, ...archived];
+  const ordered = [...visibleActive, ...visibleArchived];
   const wtRepoW = Math.max(
     0,
     ...ordered.flatMap((w) => (w.worktrees ?? []).map((wt) => wt.repo.length))
@@ -903,10 +1018,105 @@ function dispatchRepo(positionals, flags) {
       emit(() => console.log(`${check()} removed repo ${bold(res.name)}`), res);
       return;
     }
+    case "health": {
+      const name = flags.name || ctxRepo;
+      if (name) {
+        const h = repoHealth(root, name);
+        emit(() => renderHealthDetail(h), h);
+      } else {
+        const list = listRepoHealth(root);
+        emit(() => renderHealthList(list), list);
+      }
+      return;
+    }
     default:
       throw new MxError(`unknown repo command: ${action ?? "(none)"}`, "BAD_ARGS");
   }
 }
+function relativeTime(iso) {
+  if (!iso) return "never";
+  const then = Date.parse(iso);
+  const seconds = Math.max(0, Math.floor((Date.now() - then) / 1e3));
+  if (seconds < 60) return `${seconds} second${seconds === 1 ? "" : "s"} ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days} day${days === 1 ? "" : "s"} ago`;
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months} month${months === 1 ? "" : "s"} ago`;
+  const years = Math.floor(months / 12);
+  return `${years} year${years === 1 ? "" : "s"} ago`;
+}
+function renderHealthList(list) {
+  if (list.length === 0) {
+    console.log(dim("no repos yet \u2014 `mx repo add <git-url>`"));
+    return;
+  }
+  const nameW = Math.max(...list.map((h) => h.name.length));
+  for (const h of list) {
+    const marker = h.healthy ? check() : warn();
+    const name = h.name.padEnd(nameW);
+    const detail = h.healthy ? "" : `  ${dim(h.issues.join("; "))}`;
+    console.log(`${marker} ${name}${detail}`);
+  }
+}
+function renderHealthDetail(h) {
+  const rows = [];
+  const addRow = (label, value, ok, hint) => {
+    const marker = ok === void 0 ? void 0 : ok ? check() : warn();
+    rows.push({ label, value, marker, hint });
+  };
+  addRow("default branch", h.defaultBranch ?? "(unknown)");
+  const currentBranchText = h.currentBranch ?? "(detached HEAD)";
+  const branchOk = h.currentBranch !== null && h.isOnDefault;
+  addRow(
+    "current branch",
+    currentBranchText,
+    branchOk,
+    branchOk ? void 0 : h.currentBranch === null ? "HEAD is detached" : `should be ${h.defaultBranch ?? "(default)"}`
+  );
+  addRow(
+    "uncommitted",
+    `${h.uncommittedChanges} change${h.uncommittedChanges === 1 ? "" : "s"}`,
+    h.uncommittedChanges === 0,
+    h.uncommittedChanges === 0 ? void 0 : "commit or discard"
+  );
+  addRow(
+    "untracked",
+    `${h.untrackedFiles} file${h.untrackedFiles === 1 ? "" : "s"}`,
+    h.untrackedFiles === 0
+  );
+  addRow(
+    "ahead of origin",
+    h.aheadOfOrigin === null ? "(no upstream)" : `${h.aheadOfOrigin} commit${h.aheadOfOrigin === 1 ? "" : "s"}`,
+    h.aheadOfOrigin === null ? void 0 : h.aheadOfOrigin === 0
+  );
+  addRow(
+    "behind of origin",
+    h.behindOfOrigin === null ? "(no upstream)" : `${h.behindOfOrigin} commit${h.behindOfOrigin === 1 ? "" : "s"}`,
+    h.behindOfOrigin === null ? void 0 : h.behindOfOrigin === 0,
+    (h.behindOfOrigin ?? 0) > 0 ? `run \`mx repo -n ${h.name} fetch\`` : void 0
+  );
+  addRow("last fetched", relativeTime(h.lastFetchedAt));
+  const usedByCount = h.worktreesInWorks.length;
+  rows.push({
+    label: "worktrees in works",
+    value: String(usedByCount),
+    hint: usedByCount ? `used by: ${h.worktreesInWorks.join(", ")}` : void 0
+  });
+  const labelW = Math.max(...rows.map((r) => r.label.length));
+  const valueW = Math.max(...rows.map((r) => r.value.length));
+  console.log(bold(h.name));
+  for (const r of rows) {
+    const label = dim(r.label.padEnd(labelW));
+    const value = r.value.padEnd(valueW);
+    const marker = r.marker ? `  ${r.marker}` : "   ";
+    const hint = r.hint ? `  ${dim(r.hint)}` : "";
+    console.log(`  ${label}  ${value}${marker}${hint}`);
+  }
+}
 
 // src/commands/work.ts
 function need2(v, msg) {
@@ -928,7 +1138,7 @@ function dispatchWork(positionals, flags) {
   if (action === "ls") {
     const root2 = requireRuntime({ runtime: flags.runtime });
     const works = listWorksInfo(root2, {
-      includeArchived: true,
+      includeArchived: flags.all,
       onlyArchived: flags.archived
     });
     emit(() => {
@@ -1020,11 +1230,29 @@ function dispatchWork(positionals, flags) {
       return;
     }
     case "archive": {
-      if (!flags.porcelain) {
+      if (!flags.yes) {
+        if (flags.porcelain || !process.stdin.isTTY) {
+          throw new MxError(
+            `archive requires confirmation \u2014 pass --yes when running non-interactively or with --porcelain`,
+            "NEED_CONFIRMATION"
+          );
+        }
+        process.stderr.write(`${warn()} About to archive work ${bold(name)}.
+`);
         process.stderr.write(
-          `${warn()} ${dim(`Reminder: write any pending session summary into works/${name}/sessions/ before archiving.`)}
+          `${dim(`  Worktrees will be removed; folder, work.json, branches, and sessions/ are preserved.`)}
 `
         );
+        process.stderr.write(
+          `${dim(`  Make sure any pending session summary is written into works/${name}/sessions/ first.`)}
+`
+        );
+        process.stderr.write("\n");
+        if (!confirmYesNo("Proceed? (y/N) ")) {
+          process.stderr.write(`${dim("Aborted.")}
+`);
+          return;
+        }
       }
       const res = archiveWork(root, name);
       emit(() => {
@@ -1175,8 +1403,8 @@ function workPort(root, name, positionals) {
 
 // src/main.ts
 var VERSION = (() => {
-  const here = path8.dirname(fileURLToPath2(import.meta.url));
-  const pkg = JSON.parse(readFileSync2(path8.join(here, "..", "package.json"), "utf8"));
+  const here = path9.dirname(fileURLToPath2(import.meta.url));
+  const pkg = JSON.parse(readFileSync2(path9.join(here, "..", "package.json"), "utf8"));
   return pkg.version;
 })();
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roulabs/mx",
-  "version": "1.7.1",
+  "version": "1.11.0",
   "description": "mx — run several features in parallel across shared repos using git worktrees",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -20,10 +20,22 @@ Every read command takes `--porcelain` for stable JSON; parse that instead of sc
 ## What this runtime is for
 
 `mx/` is where **feature work** happens. Sessions launched here implement a feature inside a
-`works/<feature>/` folder. mx *itself* — this template, the `mx` CLI — is maintained in a separate
-**mx source checkout** (the `github.com/roulabs/mx` repo), outside this tree. If you were opened
-here to change how mx works, you're in the wrong place: switch to that repo. Don't edit `repos/`,
-`works/`, or the runtime files from here.
+`works/<feature>/` folder. mx *itself* — this template, the `mx` CLI — is maintained in the
+`github.com/roulabs/mx` source repo. There are two valid setups for that source:
+
+1. **It lives elsewhere** (the default): if you were opened here to change how mx works, you're in
+   the wrong place — switch to that repo. Don't edit `repos/`, `works/`, or the runtime files from
+   here.
+
+2. **It's hosted as a work in this runtime** (self-hosting / dogfooding): someone has run
+   `mx repo add git@github.com:roulabs/mx.git` and created one or more `works/<feature>/mx/`
+   worktrees for parallel mx development. In that case, working inside one of those worktrees IS
+   valid — follow that worktree's own `CLAUDE.md` for the developer rules. The runtime rule that
+   still applies here: **never run the worktree's locally-built mx CLI against this runtime**.
+   Locally-built mx (`pnpm mx`, `node npm/bin/mx.js`) must be pointed at a sandbox (`$PWD/.mx` or
+   `/tmp/...`) for any testing — otherwise it may re-stamp this `CLAUDE.md` with a work-in-progress
+   template. The published `mx` on `$PATH` (from `npm i -g @roulabs/mx`) is the safe one against
+   this runtime.
 
 ## Layout