@roulabs/mx 1.11.0 → 2.0.0

package/bin/mx.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import * as path9 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -49,6 +49,56 @@ function realpath(p) {
   }
 }
 
+// ../../packages/core/src/git.ts
+import { execFileSync } from "child_process";
+function git(args, opts = {}) {
+  try {
+    const out = execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...opts
+    });
+    return (out == null ? "" : String(out)).trim();
+  } catch (e) {
+    const err = e;
+    const msg = (err.stderr ?? err.stdout ?? err.message ?? "").toString().trim();
+    throw new MxError(`git ${args.join(" ")} failed: ${msg}`, "GIT");
+  }
+}
+function gitQuiet(args, opts = {}) {
+  try {
+    const out = execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      ...opts
+    });
+    return (out == null ? "" : String(out)).trim();
+  } catch {
+    return null;
+  }
+}
+function currentBranch(repoPath2) {
+  return gitQuiet(["-C", repoPath2, "rev-parse", "--abbrev-ref", "HEAD"]) ?? "(detached)";
+}
+function remoteUrl(repoPath2) {
+  return gitQuiet(["-C", repoPath2, "remote", "get-url", "origin"]) ?? gitQuiet(["-C", repoPath2, "config", "--get", "remote.origin.url"]) ?? null;
+}
+function branchExists(repoPath2, branch) {
+  return gitQuiet(["-C", repoPath2, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]) !== null;
+}
+function isDirty(worktreePath2) {
+  const s = gitQuiet(["-C", worktreePath2, "status", "--porcelain"]);
+  return s == null ? false : s.length > 0;
+}
+function remoteBranchList(repoPath2) {
+  const out = gitQuiet(["-C", repoPath2, "for-each-ref", "--format=%(refname)", "refs/remotes/origin"]);
+  if (!out) return [];
+  return out.split("\n").map((s) => s.trim()).filter((s) => s && !s.endsWith("/HEAD")).map((s) => s.replace(/^refs\/remotes\/origin\//, ""));
+}
+function resolveBase(repoPath2, base) {
+  return gitQuiet(["-C", repoPath2, "rev-parse", "--verify", `${base}^{commit}`]) ?? gitQuiet(["-C", repoPath2, "rev-parse", "--verify", `origin/${base}^{commit}`]) ?? null;
+}
+
 // ../../packages/core/src/json.ts
 import * as fs2 from "fs";
 function readJson(file) {
@@ -87,6 +137,20 @@ function stampContextIndex(targetDir, templatesDir2) {
   fs3.copyFileSync(src, dest);
   return dest;
 }
+var REPO_SCRIPTS = ["hydrate.sh", "health.sh"];
+function stampRepoScripts(containerDir, templatesDir2) {
+  const created = [];
+  for (const name of REPO_SCRIPTS) {
+    const dest = path2.join(containerDir, name);
+    if (exists(dest)) continue;
+    const src = path2.join(templatesDir2, "repo", name);
+    if (!exists(src)) throw new MxError(`missing template: ${src}`, "NO_TEMPLATE");
+    fs3.copyFileSync(src, dest);
+    fs3.chmodSync(dest, 493);
+    created.push(dest);
+  }
+  return created;
+}
 
 // ../../packages/core/src/runtime.ts
 var DEFAULT_RUNTIME = path3.join(os.homedir(), "mx");
@@ -96,9 +160,40 @@ function defaultRuntime() {
 var reposDir = (root) => path3.join(root, "repos");
 var worksDir = (root) => path3.join(root, "works");
 var repoPath = (root, name) => path3.join(reposDir(root), name);
+var repoGitDir = (root, name) => path3.join(repoPath(root, name), "git");
+var repoHydrateScript = (root, name) => path3.join(repoPath(root, name), "hydrate.sh");
+var repoHealthScript = (root, name) => path3.join(repoPath(root, name), "health.sh");
 var workDir = (root, name) => path3.join(worksDir(root), name);
 var workManifest = (root, name) => path3.join(workDir(root, name), "work.json");
 var workspaceFile = (root, name) => path3.join(workDir(root, name), `${name}.code-workspace`);
+var worktreesDir = (root, name) => path3.join(workDir(root, name), "wt");
+var worktreePath = (root, name, repo) => path3.join(worktreesDir(root, name), repo);
+var RUNTIME_VERSION = 2;
+var mxConfigFile = (root) => path3.join(root, "mx.json");
+function readMxConfig(root) {
+  const f = mxConfigFile(root);
+  if (!exists(f)) return null;
+  return readJson(f);
+}
+function readRuntimeVersion(root) {
+  const cfg = readMxConfig(root);
+  if (!cfg) return 1;
+  const n = cfg.version;
+  if (!Number.isInteger(n) || n < 1) {
+    throw new MxError(`invalid version in ${mxConfigFile(root)}: ${JSON.stringify(n)}`, "BAD_VERSION");
+  }
+  return n;
+}
+function writeRuntimeVersion(root, version) {
+  const existing = readMxConfig(root) ?? {};
+  writeJson(mxConfigFile(root), { ...existing, version });
+}
+function versionMismatchMessage(actual) {
+  if (actual > RUNTIME_VERSION) {
+    return `runtime is v${actual}, newer than this mx supports (v${RUNTIME_VERSION}). Upgrade your mx CLI: \`npm i -g @roulabs/mx@latest\`.`;
+  }
+  return `runtime is v${actual} but this mx supports runtime v${RUNTIME_VERSION}. Run \`mx migrate\` to upgrade the runtime.`;
+}
 function discoverRuntime(opts = {}) {
   const p = opts.runtime || process.env.MX_RUNTIME || DEFAULT_RUNTIME;
   return path3.resolve(p);
@@ -108,10 +203,82 @@ function requireRuntime(opts = {}) {
   if (!exists(path3.join(root, ".mx-root"))) {
     throw new MxError(`not an mx runtime (no .mx-root): ${root} \u2014 run \`mx init\``, "NO_RUNTIME");
   }
+  if (!opts.allowVersionMismatch) {
+    const v = readRuntimeVersion(root);
+    if (v !== RUNTIME_VERSION) {
+      throw new MxError(versionMismatchMessage(v), "RUNTIME_VERSION_MISMATCH");
+    }
+  }
   return root;
 }
 function listRepoNames(root) {
-  return listDirs(reposDir(root)).filter((n) => isGitRepo(repoPath(root, n)));
+  return listDirs(reposDir(root)).filter((n) => isGitRepo(repoGitDir(root, n)));
+}
+function migrateRepoLayout(root) {
+  const migrated = [];
+  for (const name of listDirs(reposDir(root))) {
+    const container = repoPath(root, name);
+    const gitdir = repoGitDir(root, name);
+    if (isGitRepo(gitdir)) continue;
+    if (!isGitRepo(container)) continue;
+    const tmp = path3.join(reposDir(root), `.${name}.mxmig`);
+    if (exists(tmp)) fs4.rmSync(tmp, { recursive: true, force: true });
+    fs4.renameSync(container, tmp);
+    fs4.mkdirSync(container, { recursive: true });
+    fs4.renameSync(tmp, gitdir);
+    try {
+      git(["-C", gitdir, "worktree", "repair"]);
+    } catch {
+    }
+    migrated.push(container);
+  }
+  return migrated;
+}
+function migrateWorkLayout(root) {
+  const changed = [];
+  for (const name of listWorkNames(root)) {
+    let work;
+    try {
+      work = readWork(root, name);
+    } catch {
+      continue;
+    }
+    const wd = workDir(root, name);
+    const wtDir = path3.join(wd, "wt");
+    for (const wt of work.worktrees ?? []) {
+      const flat = path3.join(wd, wt.repo);
+      const dest = path3.join(wtDir, wt.repo);
+      if (exists(dest) || !exists(flat)) continue;
+      fs4.mkdirSync(wtDir, { recursive: true });
+      try {
+        git(["-C", repoGitDir(root, wt.repo), "worktree", "move", flat, dest]);
+      } catch {
+        fs4.renameSync(flat, dest);
+        try {
+          git(["-C", repoGitDir(root, wt.repo), "worktree", "repair", dest]);
+        } catch {
+        }
+      }
+      changed.push(dest);
+    }
+    const wsFile = workspaceFile(root, name);
+    if (exists(wsFile)) {
+      const ws = readJson(wsFile);
+      const repos = new Set((work.worktrees ?? []).map((w) => w.repo));
+      let touched = false;
+      for (const f of ws.folders ?? []) {
+        if (f.path && !f.path.startsWith("wt/") && repos.has(f.path)) {
+          f.path = `wt/${f.path}`;
+          touched = true;
+        }
+      }
+      if (touched) {
+        writeJson(wsFile, ws);
+        changed.push(wsFile);
+      }
+    }
+  }
+  return changed;
 }
 function listWorkNames(root) {
   return listDirs(worksDir(root)).filter((n) => exists(workManifest(root, n)));
@@ -147,7 +314,7 @@ function inferContext(root) {
     return rel.split(path3.sep);
   };
   const w = segmentsUnder(worksDir(root));
-  if (w) return { work: w[0], repo: w[1] ?? null };
+  if (w) return { work: w[0], repo: w[1] === "wt" ? w[2] ?? null : null };
   const r = segmentsUnder(reposDir(root));
   if (r) return { work: null, repo: r[0] };
   return { work: null, repo: null };
@@ -155,6 +322,15 @@ function inferContext(root) {
 function initRuntime(target0, templatesDir2) {
   const target = path3.resolve(target0);
   const created = [];
+  if (exists(path3.join(target, ".mx-root"))) {
+    const v = readRuntimeVersion(target);
+    if (v !== RUNTIME_VERSION) {
+      throw new MxError(
+        `cannot init: existing runtime at ${target} is v${v}, but this mx supports v${RUNTIME_VERSION}. ` + (v < RUNTIME_VERSION ? "Run `mx migrate` to upgrade it." : "Upgrade your mx CLI."),
+        "RUNTIME_VERSION_MISMATCH"
+      );
+    }
+  }
   for (const d of [target, reposDir(target), worksDir(target)]) {
     if (!exists(d)) {
       fs4.mkdirSync(d, { recursive: true });
@@ -166,6 +342,10 @@ function initRuntime(target0, templatesDir2) {
     fs4.writeFileSync(marker, "");
     created.push(marker);
   }
+  if (!exists(mxConfigFile(target))) {
+    writeRuntimeVersion(target, RUNTIME_VERSION);
+    created.push(mxConfigFile(target));
+  }
   created.push(stampClaudeMd(target, templatesDir2));
   const ctxIndex = stampContextIndex(target, templatesDir2);
   if (ctxIndex) created.push(ctxIndex);
@@ -174,14 +354,55 @@ function initRuntime(target0, templatesDir2) {
 }
 function ensureWorkScaffolding(root, workName) {
   const created = [];
-  const sessions = path3.join(workDir(root, workName), "sessions");
-  if (!exists(sessions)) {
-    fs4.mkdirSync(sessions, { recursive: true });
-    created.push(sessions);
+  const wd = workDir(root, workName);
+  for (const d of ["wt", "scripts", "files", "tmp", "sessions"]) {
+    const p = path3.join(wd, d);
+    if (!exists(p)) {
+      fs4.mkdirSync(p, { recursive: true });
+      created.push(p);
+    }
+  }
+  const claudeMd = path3.join(wd, "CLAUDE.md");
+  if (!exists(claudeMd)) {
+    fs4.writeFileSync(claudeMd, workClaudeMd(workName));
+    created.push(claudeMd);
+  }
+  const settings = path3.join(wd, ".claude", "settings.json");
+  if (!exists(settings)) {
+    fs4.mkdirSync(path3.dirname(settings), { recursive: true });
+    fs4.writeFileSync(settings, workClaudeSettings(root));
+    created.push(settings);
   }
   return created;
 }
-function updateRuntime(root, templatesDir2) {
+function workClaudeMd(name) {
+  return `<!--
+Work-specific CLAUDE.md for "${name}".
+
+This file loads alongside the runtime's CLAUDE.md (the mx rules) for every Claude
+session started in this work folder. Put rules and context specific to THIS work
+here: what you're building, conventions, gotchas, which repo is your lane, etc.
+mx never overwrites this file after creating it \u2014 it's yours to edit.
+
+Keep ad-hoc files OUT of the work root (it holds mx-native files). Use:
+  files/    artifacts worth keeping
+  tmp/      throwaway scratch \u2014 may be deleted at any time, no guarantees
+  scripts/  ad-hoc scripts for this work
+-->
+`;
+}
+function workClaudeSettings(root) {
+  const contextDir = path3.join(root, "context");
+  const indexPath = path3.join(contextDir, "INDEX.json");
+  const command = `echo '# mx context registry \u2014 open ${contextDir}/<path>.md for relevant entries:'; cat '${indexPath}' 2>/dev/null`;
+  const settings = {
+    hooks: {
+      SessionStart: [{ matcher: "*", hooks: [{ type: "command", command }] }]
+    }
+  };
+  return JSON.stringify(settings, null, 2) + "\n";
+}
+function syncRuntime(root, templatesDir2) {
   const updated = [];
   updated.push(stampClaudeMd(root, templatesDir2));
   const ctxIndex = stampContextIndex(root, templatesDir2);
@@ -189,97 +410,98 @@ function updateRuntime(root, templatesDir2) {
   for (const workName of listWorkNames(root)) {
     updated.push(...ensureWorkScaffolding(root, workName));
   }
+  for (const repo of listRepoNames(root)) {
+    updated.push(...stampRepoScripts(repoPath(root, repo), templatesDir2));
+  }
   removeStaleRuntimeReadme(root);
   return { runtime: root, updated };
 }
 
-// ../../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";
-function git(args, opts = {}) {
-  try {
-    const out = execFileSync("git", args, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-      ...opts
-    });
-    return (out == null ? "" : String(out)).trim();
-  } catch (e) {
-    const err = e;
-    const msg = (err.stderr ?? err.stdout ?? err.message ?? "").toString().trim();
-    throw new MxError(`git ${args.join(" ")} failed: ${msg}`, "GIT");
+// ../../packages/core/src/migrations.ts
+var STEPS = {
+  1: {
+    from: 1,
+    to: 2,
+    run: (root) => {
+      const changed = [];
+      changed.push(...migrateRepoLayout(root));
+      changed.push(...migrateWorkLayout(root));
+      for (const work of listWorkNames(root)) changed.push(...ensureWorkScaffolding(root, work));
+      writeRuntimeVersion(root, 2);
+      return changed;
+    }
   }
-}
-function gitQuiet(args, opts = {}) {
-  try {
-    const out = execFileSync("git", args, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-      ...opts
-    });
-    return (out == null ? "" : String(out)).trim();
-  } catch {
-    return null;
+};
+function migrateRuntime(root) {
+  const from = readRuntimeVersion(root);
+  if (from === RUNTIME_VERSION) {
+    return { from, to: RUNTIME_VERSION, applied: [], changed: [] };
   }
-}
-function currentBranch(repoPath2) {
-  return gitQuiet(["-C", repoPath2, "rev-parse", "--abbrev-ref", "HEAD"]) ?? "(detached)";
-}
-function remoteUrl(repoPath2) {
-  return gitQuiet(["-C", repoPath2, "remote", "get-url", "origin"]) ?? gitQuiet(["-C", repoPath2, "config", "--get", "remote.origin.url"]) ?? null;
-}
-function branchExists(repoPath2, branch) {
-  return gitQuiet(["-C", repoPath2, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]) !== null;
-}
-function isDirty(worktreePath) {
-  const s = gitQuiet(["-C", worktreePath, "status", "--porcelain"]);
-  return s == null ? false : s.length > 0;
-}
-function remoteBranchList(repoPath2) {
-  const out = gitQuiet(["-C", repoPath2, "for-each-ref", "--format=%(refname)", "refs/remotes/origin"]);
-  if (!out) return [];
-  return out.split("\n").map((s) => s.trim()).filter((s) => s && !s.endsWith("/HEAD")).map((s) => s.replace(/^refs\/remotes\/origin\//, ""));
-}
-function resolveBase(repoPath2, base) {
-  return gitQuiet(["-C", repoPath2, "rev-parse", "--verify", `${base}^{commit}`]) ?? gitQuiet(["-C", repoPath2, "rev-parse", "--verify", `origin/${base}^{commit}`]) ?? null;
+  if (from > RUNTIME_VERSION) {
+    throw new MxError(
+      `runtime is v${from}, newer than this mx supports (v${RUNTIME_VERSION}). Upgrade your mx CLI: \`npm i -g @roulabs/mx@latest\`.`,
+      "CLI_TOO_OLD"
+    );
+  }
+  for (let v = from; v < RUNTIME_VERSION; v++) {
+    if (!STEPS[v]) {
+      throw new MxError(
+        `this mx has no migration from runtime v${v} to v${v + 1} \u2014 cannot upgrade v${from} \u2192 v${RUNTIME_VERSION}.`,
+        "NO_MIGRATION"
+      );
+    }
+  }
+  const applied = [];
+  const changed = [];
+  for (let v = from; v < RUNTIME_VERSION; v++) {
+    const step = STEPS[v];
+    changed.push(...step.run(root));
+    applied.push({ from: step.from, to: step.to });
+  }
+  return { from, to: RUNTIME_VERSION, applied, changed };
 }
 
 // ../../packages/core/src/repos.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import * as fs5 from "fs";
+import * as path4 from "path";
 function repoNameFromUrl(url) {
   const base = url.split("/").pop() || url;
   return base.replace(/\.git$/, "");
 }
 function repoAdd(root, url, name0) {
   const name = name0 || repoNameFromUrl(url);
-  const dest = repoPath(root, name);
-  if (exists(dest)) throw new MxError(`repo already exists: ${name}`, "EXISTS");
-  git(["clone", url, dest], { stdio: ["ignore", "inherit", "inherit"] });
-  return { name, path: dest, remote: remoteUrl(dest), branch: currentBranch(dest) };
+  const container = repoPath(root, name);
+  if (exists(container)) throw new MxError(`repo already exists: ${name}`, "EXISTS");
+  const gitdir = repoGitDir(root, name);
+  fs5.mkdirSync(container, { recursive: true });
+  git(["clone", url, gitdir], { stdio: ["ignore", "inherit", "inherit"] });
+  return { name, path: container, remote: remoteUrl(gitdir), branch: currentBranch(gitdir) };
 }
 function listReposInfo(root) {
   return listRepoNames(root).map((name) => ({
     name,
-    branch: currentBranch(repoPath(root, name)),
-    remote: remoteUrl(repoPath(root, name))
+    // path is the container; branch/remote come from the git/ clone.
+    path: repoPath(root, name),
+    branch: currentBranch(repoGitDir(root, name)),
+    remote: remoteUrl(repoGitDir(root, name))
   }));
 }
 function repoFetch(root, name) {
-  const rp = repoPath(root, name);
+  const rp = repoGitDir(root, name);
   if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
   git(["-C", rp, "fetch", "--all", "--prune", "--tags"]);
   gitQuiet(["-C", rp, "merge", "--ff-only", "@{u}"]);
   return { name, branch: currentBranch(rp), remoteBranches: remoteBranchList(rp) };
 }
 function repoInfo(root, name) {
-  const rp = repoPath(root, name);
+  const rp = repoGitDir(root, name);
   if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
   const usedBy = listWorkNames(root).filter((w) => findWorktree(readWork(root, w), name));
   return {
     name,
-    path: rp,
+    path: repoPath(root, name),
+    // the container (repo home)
     branch: currentBranch(rp),
     remote: remoteUrl(rp),
     worktreesInWorks: usedBy
@@ -321,8 +543,30 @@ function lastFetched(rp) {
   if (!exists(fh)) return null;
   return fs5.statSync(fh).mtime.toISOString();
 }
+function runHealthScript(root, name) {
+  const script = repoHealthScript(root, name);
+  if (!exists(script)) return null;
+  try {
+    const out = execFileSync2(script, [], {
+      cwd: repoGitDir(root, name),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      env: {
+        ...process.env,
+        MX_RUNTIME: root,
+        MX_REPO: name,
+        MX_REPO_PATH: repoPath(root, name),
+        MX_GIT_DIR: repoGitDir(root, name)
+      }
+    });
+    const trimmed = out.trim();
+    return trimmed.length ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
 function repoHealth(root, name) {
-  const rp = repoPath(root, name);
+  const rp = repoGitDir(root, name);
   if (!isGitRepo(rp)) throw new MxError(`no such repo: ${name}`, "NO_REPO");
   const defaultBranch = originDefaultBranch(rp);
   const current = currentBranchOrNull(rp);
@@ -355,7 +599,8 @@ function repoHealth(root, name) {
   }
   return {
     name,
-    path: rp,
+    path: repoPath(root, name),
+    // the container (repo home)
     defaultBranch,
     currentBranch: current,
     isOnDefault,
@@ -366,15 +611,15 @@ function repoHealth(root, name) {
     lastFetchedAt,
     worktreesInWorks,
     healthy: issues.length === 0,
-    issues
+    issues,
+    extra: runHealthScript(root, name)
   };
 }
 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");
+  if (!isGitRepo(repoGitDir(root, name))) throw new MxError(`no such repo: ${name}`, "NO_REPO");
   const usedBy = listWorkNames(root).filter((w) => findWorktree(readWork(root, w), name));
   if (usedBy.length) {
     throw new MxError(
@@ -382,25 +627,25 @@ function repoRemove(root, name) {
       "IN_USE"
     );
   }
-  fs5.rmSync(rp, { recursive: true, force: true });
+  fs5.rmSync(repoPath(root, name), { recursive: true, force: true });
   return { name, removed: true };
 }
 
 // ../../packages/core/src/works.ts
 import * as fs6 from "fs";
-import * as path5 from "path";
 function addFolderToWorkspace(root, name, repo) {
   const file = workspaceFile(root, name);
   const ws = exists(file) ? readJson(file) : { folders: [], settings: {} };
   ws.folders = ws.folders ?? [];
-  if (!ws.folders.some((f) => f.path === repo)) ws.folders.push({ name: repo, path: repo });
+  const rel = `wt/${repo}`;
+  if (!ws.folders.some((f) => f.path === rel)) ws.folders.push({ name: repo, path: rel });
   writeJson(file, ws);
 }
 function removeFolderFromWorkspace(root, name, repo) {
   const file = workspaceFile(root, name);
   if (!exists(file)) return;
   const ws = readJson(file);
-  ws.folders = (ws.folders ?? []).filter((f) => f.path !== repo);
+  ws.folders = (ws.folders ?? []).filter((f) => f.path !== `wt/${repo}`);
   writeJson(file, ws);
 }
 function clearWorkspaceFolders(root, name) {
@@ -423,6 +668,7 @@ function workNew(root, name, description = "") {
 function listWorksInfo(root, opts = {}) {
   return listWorkNames(root).map((name) => ({
     ...readWork(root, name),
+    path: workDir(root, name),
     sessions: countSessions(root, name)
   })).filter((w) => {
     if (opts.onlyArchived) return w.isArchived === true;
@@ -446,13 +692,14 @@ function workPath(root, name) {
 }
 function worktreeAdd(root, name, repo, opts = {}) {
   const work = readWork(root, name);
-  const rp = repoPath(root, repo);
+  const rp = repoGitDir(root, repo);
   if (!isGitRepo(rp)) throw new MxError(`no such repo: ${repo}`, "NO_REPO");
   if (findWorktree(work, repo)) {
     throw new MxError(`work "${name}" already has worktree for ${repo}`, "EXISTS");
   }
   const branch = opts.branch || name;
-  const dest = path5.join(workDir(root, name), repo);
+  const dest = worktreePath(root, name, repo);
+  fs6.mkdirSync(worktreesDir(root, name), { recursive: true });
   if (branchExists(rp, branch)) {
     git(["-C", rp, "worktree", "add", dest, branch]);
   } else {
@@ -479,11 +726,11 @@ 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 = path5.join(workDir(root, name), repo);
+  const dest = worktreePath(root, name, repo);
   if (exists(dest) && isDirty(dest)) {
     throw new MxError(`worktree ${repo} has uncommitted changes \u2014 commit or discard them first`, "DIRTY");
   }
-  git(["-C", repoPath(root, repo), "worktree", "remove", dest]);
+  git(["-C", repoGitDir(root, repo), "worktree", "remove", dest]);
   work.worktrees = work.worktrees.filter((w) => w.repo !== repo);
   writeWork(root, work);
   removeFolderFromWorkspace(root, name, repo);
@@ -499,7 +746,7 @@ function workDestroy(root, name, opts = {}) {
   const work = readWork(root, name);
   const dirty = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path5.join(workDir(root, name), wt.repo);
+    const dest = worktreePath(root, name, wt.repo);
     if (exists(dest) && isDirty(dest)) dirty.push(wt.repo);
   }
   if (dirty.length) {
@@ -510,8 +757,8 @@ function workDestroy(root, name, opts = {}) {
   }
   const removed = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path5.join(workDir(root, name), wt.repo);
-    if (exists(dest)) git(["-C", repoPath(root, wt.repo), "worktree", "remove", dest]);
+    const dest = worktreePath(root, name, wt.repo);
+    if (exists(dest)) git(["-C", repoGitDir(root, wt.repo), "worktree", "remove", dest]);
     removed.push(wt.repo);
   }
   fs6.rmSync(workDir(root, name), { recursive: true, force: true });
@@ -524,7 +771,7 @@ function archiveWork(root, name) {
   }
   const dirty = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path5.join(workDir(root, name), wt.repo);
+    const dest = worktreePath(root, name, wt.repo);
     if (exists(dest) && isDirty(dest)) dirty.push(wt.repo);
   }
   if (dirty.length) {
@@ -535,8 +782,8 @@ function archiveWork(root, name) {
   }
   const removed = [];
   for (const wt of work.worktrees ?? []) {
-    const dest = path5.join(workDir(root, name), wt.repo);
-    if (exists(dest)) git(["-C", repoPath(root, wt.repo), "worktree", "remove", dest]);
+    const dest = worktreePath(root, name, wt.repo);
+    if (exists(dest)) git(["-C", repoGitDir(root, wt.repo), "worktree", "remove", dest]);
     removed.push(wt.repo);
   }
   clearWorkspaceFolders(root, name);
@@ -558,7 +805,7 @@ function unarchiveWork(root, name, overrides = {}) {
   }));
   const missing = [];
   for (const d of desired) {
-    const rp = repoPath(root, d.repo);
+    const rp = repoGitDir(root, d.repo);
     if (!isGitRepo(rp)) {
       throw new MxError(`pristine clone missing for repo: ${d.repo}`, "NO_REPO");
     }
@@ -574,8 +821,9 @@ function unarchiveWork(root, name, overrides = {}) {
   }
   const restored = [];
   for (const d of desired) {
-    const dest = path5.join(workDir(root, name), d.repo);
-    git(["-C", repoPath(root, d.repo), "worktree", "add", dest, d.branch]);
+    const dest = worktreePath(root, name, d.repo);
+    fs6.mkdirSync(worktreesDir(root, name), { recursive: true });
+    git(["-C", repoGitDir(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 });
   }
@@ -654,9 +902,9 @@ function portList(root, name) {
 }
 
 // ../../packages/core/src/status.ts
-import * as path6 from "path";
+import * as path5 from "path";
 function countContextEntries(root) {
-  const indexPath = path6.join(root, "context", "INDEX.json");
+  const indexPath = path5.join(root, "context", "INDEX.json");
   if (!exists(indexPath)) return 0;
   try {
     const data = readJson(indexPath);
@@ -696,7 +944,9 @@ function parseArgs(argv) {
     force: false,
     yes: false,
     all: false,
-    archived: false
+    archived: false,
+    open: false,
+    noHydrate: false
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -714,6 +964,10 @@ function parseArgs(argv) {
       flags.all = true;
     } else if (a === "--archived") {
       flags.archived = true;
+    } else if (a === "--open" || a === "-o") {
+      flags.open = true;
+    } else if (a === "--no-hydrate") {
+      flags.noHydrate = true;
     } else if (a.startsWith("--") && a.includes("=")) {
       const eq = a.indexOf("=");
       const key = VALUE_FLAGS[a.slice(0, eq)];
@@ -730,6 +984,7 @@ function parseArgs(argv) {
 
 // src/output.ts
 import { spawnSync } from "child_process";
+import * as os2 from "os";
 var USE_STYLE = process.stdout.isTTY && !process.env.NO_COLOR;
 function wrap(s, code) {
   return USE_STYLE ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -746,6 +1001,11 @@ function check() {
 function warn() {
   return "\u26A0";
 }
+function tildify(p) {
+  const home = os2.homedir();
+  if (p === home) return "~";
+  return p.startsWith(home + "/") ? "~" + p.slice(home.length) : p;
+}
 function confirmYesNo(prompt) {
   if (!process.stdin.isTTY) return false;
   process.stdout.write(prompt);
@@ -791,7 +1051,9 @@ var HELP = `mx \u2014 control panel for the mx runtime
 Global:
   mx init [path]                         scaffold/adopt a runtime (default ~/mx)
   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 sync                                re-stamp runtime files (CLAUDE.md, scaffolding) from current templates \u2014 same-major, non-breaking
+  mx update                              self-update the mx CLI within its major (npm i -g); flags a newer major if one exists
+  mx migrate                             upgrade an older-version runtime to the version this CLI supports (the only command allowed on a mismatched runtime)
   mx help | version
 
 Repos (pristine clones):
@@ -804,14 +1066,15 @@ Repos (pristine clones):
   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 new <name> [--description <t>] [-o|--open]    creates folder + empty work.json + sessions/; -o opens a fullscreen Terminal (cd'd in) + editor on the workspace (macOS)
   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>
-  mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>]
+  mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>] [--no-hydrate]   runs the repo's hydrate.sh after add unless --no-hydrate
   mx work -n <name> worktree ls [--porcelain]
   mx work -n <name> worktree rm <repo>                  refuses on uncommitted changes; keeps branch
+  mx work -n <name> worktree hydrate <repo>             re-run the repo's hydrate.sh against its worktree
   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]
@@ -827,20 +1090,89 @@ Runtime discovery: --runtime <path>  ->  $MX_RUNTIME  ->  default ~/mx.
 `;
 
 // src/commands/global.ts
-import * as path8 from "path";
+import * as path7 from "path";
 
 // src/paths.ts
-import * as path7 from "path";
+import { readFileSync as readFileSync2 } from "fs";
+import * as path6 from "path";
 import { fileURLToPath } from "url";
 function templatesDir() {
   if (process.env.MX_TEMPLATES_DIR) return process.env.MX_TEMPLATES_DIR;
-  const here = path7.dirname(fileURLToPath(import.meta.url));
-  return path7.join(here, "..", "templates");
+  const here = path6.dirname(fileURLToPath(import.meta.url));
+  return path6.join(here, "..", "templates");
+}
+function cliVersion() {
+  const here = path6.dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync2(path6.join(here, "..", "package.json"), "utf8"));
+  return pkg.version;
+}
+
+// src/selfupdate.ts
+import { spawnSync as spawnSync2 } from "child_process";
+var PKG = "@roulabs/mx";
+function major(v) {
+  return Number.parseInt(v.split(".")[0], 10) || 0;
+}
+function npmAvailable() {
+  try {
+    const r = spawnSync2("npm", ["--version"], { stdio: ["ignore", "ignore", "ignore"] });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+function npmViewJson(spec, field) {
+  const r = spawnSync2("npm", ["view", spec, field, "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (r.status !== 0 || !r.stdout) return null;
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    return null;
+  }
+}
+function latestForRange(range) {
+  const v = npmViewJson(`${PKG}@${range}`, "version");
+  if (typeof v === "string") return v;
+  if (Array.isArray(v) && v.length) return String(v[v.length - 1]);
+  return null;
+}
+function latestOverall() {
+  const v = npmViewJson(PKG, "version");
+  return typeof v === "string" ? v : null;
+}
+function selfUpdate(porcelain2) {
+  const current = cliVersion();
+  const curMajor = major(current);
+  const info = {
+    package: PKG,
+    current,
+    npmAvailable: false,
+    latestInMajor: null,
+    updated: false,
+    installFailed: false,
+    newMajor: null
+  };
+  if (!npmAvailable()) return info;
+  info.npmAvailable = true;
+  info.latestInMajor = latestForRange(`^${curMajor}`);
+  const overall = latestOverall();
+  if (overall && major(overall) > curMajor) info.newMajor = major(overall);
+  if (info.latestInMajor && info.latestInMajor !== current) {
+    const r = spawnSync2("npm", ["i", "-g", `${PKG}@^${curMajor}`], {
+      stdio: porcelain2 ? ["ignore", "pipe", "pipe"] : "inherit"
+    });
+    if (r.status === 0) info.updated = true;
+    else info.installFailed = true;
+  }
+  return info;
 }
 
 // src/commands/global.ts
 function runtimeEnvHint(runtime) {
-  const envRuntime = process.env.MX_RUNTIME ? path8.resolve(process.env.MX_RUNTIME) : null;
+  const envRuntime = process.env.MX_RUNTIME ? path7.resolve(process.env.MX_RUNTIME) : null;
   if (envRuntime === runtime) {
     return ["", `${dim("$MX_RUNTIME already points here \u2014 you're set.")}`];
   }
@@ -874,19 +1206,62 @@ function runGlobal(positionals, flags) {
       emit(() => renderStatus(data), data);
       return;
     }
-    case "update": {
+    case "sync": {
       const root = requireRuntime({ runtime: flags.runtime });
-      const res = updateRuntime(root, templatesDir());
+      const res = syncRuntime(root, templatesDir());
       emit(() => {
-        console.log(`${check()} Updated runtime at ${bold(res.runtime)}`);
+        console.log(`${check()} Synced runtime at ${bold(res.runtime)}`);
         for (const p of res.updated) console.log(`  ${dim(`+ ${p}`)}`);
       }, res);
       return;
     }
+    case "migrate": {
+      const root = requireRuntime({ runtime: flags.runtime, allowVersionMismatch: true });
+      const res = migrateRuntime(root);
+      emit(() => {
+        if (res.applied.length === 0) {
+          console.log(`${check()} Runtime already at v${res.to} \u2014 nothing to migrate.`);
+          return;
+        }
+        const steps = res.applied.map((a) => `v${a.from}\u2192v${a.to}`).join(", ");
+        console.log(
+          `${check()} Migrated runtime ${bold(`v${res.from}\u2192v${res.to}`)} ${dim(`(${steps})`)}`
+        );
+        for (const p of res.changed) console.log(`  ${dim(`~ ${p}`)}`);
+      }, res);
+      return;
+    }
+    case "update": {
+      const info = selfUpdate(flags.porcelain);
+      emit(() => renderSelfUpdate(info), info);
+      return;
+    }
     default:
       throw new MxError(`unknown command: ${positionals[0]}`, "BAD_ARGS");
   }
 }
+function renderSelfUpdate(info) {
+  const curMajor = Number.parseInt(info.current.split(".")[0], 10) || 0;
+  const manual = `npm i -g ${info.package}@^${curMajor}`;
+  if (!info.npmAvailable) {
+    console.log(`${warn()} npm not found \u2014 update manually: ${bold(manual)}`);
+  } else if (info.installFailed) {
+    console.log(`${warn()} self-update failed \u2014 try: ${bold(manual)}`);
+  } else if (info.updated) {
+    console.log(
+      `${check()} Updated mx to ${bold(`v${info.latestInMajor}`)} ${dim(`(was v${info.current})`)}`
+    );
+  } else {
+    console.log(`${check()} mx is up to date ${dim(`(v${info.current}, latest in v${curMajor}.x)`)}`);
+  }
+  if (info.newMajor) {
+    console.log();
+    console.log(`${warn()} A new major release ${bold(`mx v${info.newMajor}`)} is available.`);
+    console.log(
+      `  ${dim(`Upgrade (optional): npm i -g ${info.package}@${info.newMajor}, then `)}${bold("mx migrate")}`
+    );
+  }
+}
 function renderStatus(data) {
   console.log();
   console.log(`  ${bold("mx")} ${dim("\xB7")} ${data.runtime}`);
@@ -958,6 +1333,7 @@ function dispatchRepo(positionals, flags) {
     case "add": {
       const url = need(positionals[2], "usage: mx repo add <git-url> [--name <n>]");
       const res = repoAdd(root, url, flags.name);
+      stampRepoScripts(repoPath(root, res.name), templatesDir());
       emit(() => console.log(`${check()} cloned ${bold(res.name)} ${dim(`\u2192 ${res.path}`)}`), res);
       return;
     }
@@ -975,6 +1351,7 @@ function dispatchRepo(positionals, flags) {
           const branch = dim(r.branch.padEnd(branchW));
           const remote = dim(r.remote ?? "(no remote)");
           console.log(`\u2022 ${name}  ${branch}  ${remote}`);
+          console.log(`  ${dim(tildify(r.path))}`);
         }
       }, repos);
       return;
@@ -1116,6 +1493,115 @@ function renderHealthDetail(h) {
     const hint = r.hint ? `  ${dim(r.hint)}` : "";
     console.log(`  ${label}  ${value}${marker}${hint}`);
   }
+  if (h.extra) {
+    console.log();
+    console.log(`  ${dim("health.sh")}`);
+    for (const line of h.extra.split("\n")) console.log(`    ${dim(line)}`);
+  }
+}
+
+// src/commands/work.ts
+import * as path8 from "path";
+
+// src/open.ts
+import { execFileSync as execFileSync3 } from "child_process";
+function osascript(script) {
+  try {
+    execFileSync3("osascript", ["-e", script], { stdio: ["ignore", "ignore", "pipe"] });
+  } catch (e) {
+    const err = e;
+    throw new MxError(
+      `osascript failed: ${(err.stderr ?? err.message ?? "").toString().trim()}`,
+      "OSASCRIPT"
+    );
+  }
+}
+function aplStr(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function openWorkLayout(workdir, workspace) {
+  if (process.platform !== "darwin") {
+    throw new MxError("-o/--open is only supported on macOS", "UNSUPPORTED");
+  }
+  let editorProcess = "Cursor";
+  try {
+    execFileSync3("open", ["-a", "Cursor", workspace], { stdio: "ignore" });
+  } catch {
+    try {
+      execFileSync3("open", ["-a", "Visual Studio Code", workspace], { stdio: "ignore" });
+      editorProcess = "Code";
+    } catch {
+      editorProcess = "";
+    }
+  }
+  osascript(
+    [
+      'tell application "Terminal"',
+      "  activate",
+      "  set winCountBefore to count of windows",
+      `  do script "cd \\"${aplStr(workdir)}\\""`,
+      "  delay 0.5",
+      "  set winCountAfter to count of windows",
+      "end tell",
+      "if winCountAfter is less than or equal to winCountBefore then",
+      '  tell application "System Events" to tell process "Terminal"',
+      "    try",
+      '      click menu item "Move Tab to New Window" of menu "Window" of menu bar 1',
+      "      delay 0.4",
+      "    end try",
+      "  end tell",
+      "end if",
+      'tell application "System Events" to tell process "Terminal"',
+      "  try",
+      '    set value of attribute "AXFullScreen" of window 1 to true',
+      "  end try",
+      "end tell"
+    ].join("\n")
+  );
+  if (editorProcess) {
+    const appName = editorProcess === "Code" ? "Visual Studio Code" : "Cursor";
+    osascript(
+      [
+        `tell application "${appName}" to activate`,
+        // wait until the app is frontmost (cold launch can take a few seconds)
+        'tell application "System Events"',
+        "  set n to 0",
+        `  repeat until (exists process "${editorProcess}") and (frontmost of process "${editorProcess}" is true)`,
+        "    delay 0.3",
+        "    set n to n + 1",
+        "    if n > 40 then exit repeat",
+        "  end repeat",
+        "end tell",
+        // let the workbench finish loading so it accepts the keybinding
+        "delay 1.2",
+        'tell application "System Events" to key code 3 using {control down, command down}'
+      ].join("\n")
+    );
+  }
+}
+
+// src/hydrate.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+function runWorktreeHydrate(ctx, quiet) {
+  const script = repoHydrateScript(ctx.root, ctx.repo);
+  if (!existsSync2(script)) return { ran: false, ok: true, missing: true };
+  const env = {
+    ...process.env,
+    MX_RUNTIME: ctx.root,
+    MX_WORK: ctx.work,
+    MX_REPO: ctx.repo,
+    MX_WORKTREE_PATH: ctx.worktreePath,
+    MX_BRANCH: ctx.branch,
+    MX_BASE: ctx.base ?? "",
+    MX_WORK_PATH: workPath(ctx.root, ctx.work).path
+  };
+  const r = spawnSync3(script, [ctx.worktreePath, ctx.branch], {
+    cwd: ctx.worktreePath,
+    env,
+    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit"
+  });
+  return { ran: true, ok: r.status === 0, missing: false };
 }
 
 // src/commands/work.ts
@@ -1127,12 +1613,21 @@ function dispatchWork(positionals, flags) {
   const action = positionals[1];
   if (action === "new") {
     const root2 = requireRuntime({ runtime: flags.runtime });
-    const name2 = need2(positionals[2], "usage: mx work new <name> [--description <text>]");
+    const name2 = need2(positionals[2], "usage: mx work new <name> [--description <text>] [-o|--open]");
     const res = workNew(root2, name2, flags.description ?? "");
     emit(() => {
       console.log(`${check()} created work ${bold(res.name)}`);
       console.log(`  ${dim(res.path)}`);
     }, res);
+    if (flags.open) {
+      try {
+        openWorkLayout(res.path, workspaceFile(root2, res.name));
+      } catch (e) {
+        const msg = e instanceof MxError ? e.message : String(e);
+        process.stderr.write(`${warn()} ${dim(`could not open layout: ${msg}`)}
+`);
+      }
+    }
     return;
   }
   if (action === "ls") {
@@ -1157,6 +1652,7 @@ function dispatchWork(positionals, flags) {
         const chip = w.isArchived === true ? `  ${dim(`[archived ${(w.archived_at ?? "").slice(0, 10)}]`)}` : "";
         const styledName = w.isArchived === true ? dim(w.name) : bold(w.name);
         console.log(`\u2022 ${styledName}${chip}`);
+        console.log(`  ${dim(tildify(w.path))}`);
         if (w.description) {
           console.log(`  ${dim(`\u2014 ${w.description}`)}`);
         }
@@ -1294,7 +1790,7 @@ function workWorktree(root, name, positionals, flags) {
     case "add": {
       const repo = need2(
         positionals[3],
-        "usage: mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>]"
+        "usage: mx work -n <name> worktree add <repo> [--branch <b>] [--base <ref>] [--no-hydrate]"
       );
       const res = worktreeAdd(root, name, repo, { branch: flags.branch, base: flags.base });
       emit(
@@ -1303,6 +1799,18 @@ function workWorktree(root, name, positionals, flags) {
         ),
         res
       );
+      if (!flags.noHydrate) {
+        const outcome = runWorktreeHydrate(
+          { root, work: name, repo: res.repo, worktreePath: res.path, branch: res.branch, base: flags.base },
+          flags.porcelain
+        );
+        if (outcome.ran && !outcome.ok && !flags.porcelain) {
+          process.stderr.write(
+            `${warn()} ${dim(`hydrate.sh for ${res.repo} exited non-zero \u2014 worktree kept. Re-run: mx work -n ${name} worktree hydrate ${res.repo}`)}
+`
+          );
+        }
+      }
       return;
     }
     case "ls": {
@@ -1334,6 +1842,31 @@ function workWorktree(root, name, positionals, flags) {
       );
       return;
     }
+    case "hydrate": {
+      const repo = need2(positionals[3], "usage: mx work -n <name> worktree hydrate <repo>");
+      const wt = worktreeList(root, name).find((w) => w.repo === repo);
+      if (!wt) throw new MxError(`work "${name}" has no worktree for ${repo}`, "NO_WORKTREE");
+      const worktreePath2 = path8.join(workPath(root, name).path, "wt", repo);
+      const outcome = runWorktreeHydrate(
+        { root, work: name, repo, worktreePath: worktreePath2, branch: wt.branch },
+        flags.porcelain
+      );
+      if (outcome.missing) {
+        emit(
+          () => console.log(dim(`no hydrate.sh for ${repo} \u2014 nothing to run`)),
+          { work: name, repo, ran: false }
+        );
+        return;
+      }
+      if (!outcome.ok) throw new MxError(`hydrate.sh for ${repo} exited non-zero`, "HYDRATE_FAILED");
+      emit(() => console.log(`${check()} hydrated ${bold(repo)}`), {
+        work: name,
+        repo,
+        ran: true,
+        ok: true
+      });
+      return;
+    }
     default:
       throw new MxError(`unknown worktree command: ${sub ?? "(none)"}`, "BAD_ARGS");
   }
@@ -1404,7 +1937,7 @@ function workPort(root, name, positionals) {
 // src/main.ts
 var VERSION = (() => {
   const here = path9.dirname(fileURLToPath2(import.meta.url));
-  const pkg = JSON.parse(readFileSync2(path9.join(here, "..", "package.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync3(path9.join(here, "..", "package.json"), "utf8"));
   return pkg.version;
 })();
 function main() {
@@ -1423,7 +1956,9 @@ function main() {
     switch (positionals[0]) {
       case "init":
       case "status":
+      case "sync":
       case "update":
+      case "migrate":
         return runGlobal(positionals, flags);
       case "repo":
         return dispatchRepo(positionals, flags);