@mutmutco/cli 2.6.0 → 2.8.0

package/README.md

@@ -36,7 +36,7 @@ mmi-cli doctor --json
   KB curation without echoing the plan body.
   `mmi-cli plan` remains a compatibility alias.
 - `mmi-cli secrets where|list|get|set|edit|rm|use|grant|revoke` manages two-tier project/org secrets without logging values; `where` prints the vault layout + well-known keys, and values move over TLS in the request body — never an argument.
-- `mmi-cli project list|get|resolve|set` reads the DDB org registry — a project's identity + board coords + deploy coordinates (`resolve` reads deploy coords, which are OIDC-gated; `set` is master-only).
+- `mmi-cli project list|get|resolve|doctor|heal|readiness|set` reads and repairs Hub-owned v2 readiness state. `doctor --v2 --json` diagnoses central deploy/secrets readiness, `heal --v2 --apply` fixes only registry-owned defaults, and `readiness --update-issue` updates the repo's v2 readiness issue; `set` is master-only.
 - `mmi-cli registry org` reads org-level constants from the registry (`ORG#config`).
 - `mmi-cli oauth plan|verify` prints a repo's canonical Google OAuth URI set (read from the registry) and verifies the client is port-agnostic.
 - `mmi-cli issue create` creates typed, prioritized GitHub issues (priority sets the board field, not a label) and queues related-issue discovery.

package/dist/index.cjs

@@ -3341,6 +3341,7 @@ function resumeCue() {
 
 // src/saga-note.ts
 var AGENT_SURFACE_TOKENS = ["claude", "codex", "cursor", "gemini"];
+var ROUTE_LEVEL_403 = "saga API route-level 403 from GitHubAuthorizer cache/policy";
 function agentSurface() {
   const surface = process.env.MMI_AGENT_SURFACE || "claude";
   if (AGENT_SURFACE_TOKENS.includes(surface)) return surface;
@@ -3372,6 +3373,10 @@ function buildNoteCapture(summary, o, id, evidence) {
     anchorForce: o.anchorForce || void 0
   };
 }
+function formatCaptureFailure(status, message) {
+  if (status === 403 && message === "Forbidden") return `saga: ${ROUTE_LEVEL_403} (HTTP 403)`;
+  return `saga: HTTP ${status}`;
+}
 
 // src/version-lag.ts
 var VERSION_LABEL = "installed plugin/adapter cache freshness";
@@ -4246,6 +4251,13 @@ function ghError(e) {
 }
 
 // src/gc.ts
+function buildRemoteBranchCleanupReport(branch, input) {
+  if (!input.attempted) return { name: branch, status: "not-attempted", reason: input.reason };
+  if (input.existsAfter === true) return { name: branch, status: "failed", reason: "still-present-after-delete" };
+  if (input.existedBefore === false && input.existsAfter === false) return { name: branch, status: "already-gone" };
+  if (input.existsAfter === false) return { name: branch, status: "deleted" };
+  return { name: branch, status: "not-attempted", reason: input.reason ?? "remote-check-unavailable" };
+}
 var DEFAULT_PROTECTED = /* @__PURE__ */ new Set(["development", "main", "master", "rc"]);
 function groupedPrs(prs) {
   const out = /* @__PURE__ */ new Map();
@@ -4353,6 +4365,63 @@ function branchMissingFromList(branch, stdout) {
   const names = stdout.split(/\r?\n/).map((line) => line.replace(/^\*\s*/, "").trim()).filter(Boolean);
   return !names.includes(branch);
 }
+function shellQuote(value) {
+  return `"${value.replace(/(["\\])/g, "\\$1")}"`;
+}
+function safeWorktreeRemoveCommand(safeCwd, targetPath) {
+  const prefix = safeCwd ? `git -C ${shellQuote(safeCwd)}` : "git";
+  return `${prefix} worktree remove --force ${shellQuote(targetPath)}`;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function cleanupPrMergeLocalBranch(branch, options) {
+  const report = {
+    branch,
+    localBranch: { name: branch, status: "not-attempted", reason: branch ? "pending" : "missing-branch" }
+  };
+  if (!branch) return report;
+  let afterWorktrees = [];
+  try {
+    afterWorktrees = parseWorktreePorcelain(await options.execGit(["worktree", "list", "--porcelain"]));
+  } catch (e) {
+    report.localBranch = { name: branch, status: "not-attempted", reason: "worktree-list-failed", error: errorMessage(e) };
+    return report;
+  }
+  const beforeWorktrees = options.beforeWorktrees ?? [];
+  const wtPath = selectPrMergeCleanupWorktree(branch, beforeWorktrees, afterWorktrees, options.startingPath);
+  const safeCwd = selectSafeWorktreeCwd([...afterWorktrees, ...beforeWorktrees], wtPath);
+  const git = (args) => safeCwd ? options.execGit(["-C", safeCwd, ...args]) : options.execGit(args);
+  if (wtPath) {
+    try {
+      await git(["worktree", "remove", "--force", wtPath]);
+      report.worktree = { path: wtPath, status: "removed" };
+    } catch (e) {
+      report.worktree = {
+        path: wtPath,
+        status: "failed",
+        error: errorMessage(e),
+        safeCleanupCommand: safeWorktreeRemoveCommand(safeCwd, wtPath)
+      };
+      report.localBranch = { name: branch, status: "not-attempted", reason: "worktree-removal-failed" };
+      return report;
+    }
+  }
+  const current = (await git(["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "") || "").trim();
+  if (branch === current) {
+    report.localBranch = { name: branch, status: "not-attempted", reason: "current-branch" };
+    return report;
+  }
+  try {
+    await git(["branch", "-D", branch]);
+    report.localBranch = { name: branch, status: "deleted" };
+  } catch (e) {
+    const remaining = await git(["branch", "--list", branch]).catch(() => "");
+    report.localBranch = branchMissingFromList(branch, remaining) ? { name: branch, status: "already-gone" } : { name: branch, status: "failed", error: errorMessage(e) };
+  }
+  if (wtPath) await git(["worktree", "prune"]).catch(() => "");
+  return report;
+}
 function formatGcPlan(plan2, apply) {
   const lines = [`mmi-cli gc: ${apply ? "apply" : "dry-run"}`];
   if (!plan2.branches.length && !plan2.trackingRefs.length) lines.push("nothing to clean");
@@ -4403,8 +4472,9 @@ function trainPlan(command) {
       { label: "verify current branch is development", gated: true },
       { label: "verify registry META for this project", command: "mmi-cli project get <owner/repo>", gated: true },
       { label: "preflight required rc secret names", command: "mmi-cli secrets preflight --stage rc --repo <owner/repo>", gated: true },
+      { label: "for Hub distribution changes, verify the release bump is already landed before touching rc", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view", gated: true },
       { label: "merge development to rc", gated: true },
-      { label: "dispatch central tenant deploy for rc", command: "gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub -f slug=<slug> -f repo=<owner/repo> -f ref=rc -f stage=rc", gated: true }
+      { label: "trigger the deploy path for this repo model", command: "tenant-container: gh workflow run tenant-deploy.yml ...; hub-serverless: no manual dispatch, deploy.yml auto-fires on rc push", gated: true }
     ];
   }
   if (command === "release") {
@@ -4414,8 +4484,9 @@ function trainPlan(command) {
       { label: "verify registry META for this project", command: "mmi-cli project get <owner/repo>", gated: true },
       { label: "preflight required main secret names", command: "mmi-cli secrets preflight --stage main --repo <owner/repo>", gated: true },
       { label: "merge rc to main", gated: true },
+      { label: "for Hub distribution changes, verify the promoted SHA carries the release bump", command: "node scripts/release-distribution.mjs verify <release-tag> --skip-npm-view", gated: true },
       { label: "tag release and publish GitHub Release", gated: true },
-      { label: "dispatch central tenant deploy for main", command: "gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub -f slug=<slug> -f repo=<owner/repo> -f ref=main -f stage=main", gated: true },
+      { label: "trigger the deploy path for this repo model", command: "tenant-container: gh workflow run tenant-deploy.yml ...; hub-serverless: no manual dispatch, deploy.yml + publish.yml auto-fire on the release", gated: true },
       { label: "roll development forward", gated: true }
     ];
   }
@@ -5695,6 +5766,24 @@ async function fetchProjectBySlug(slug, deps) {
     return null;
   }
 }
+async function fetchDeployStatusBySlug(slug, deps) {
+  if (!deps.baseUrl || !slug) return null;
+  const token = await deps.token();
+  if (!token) return null;
+  const doFetch = deps.fetch ?? fetch;
+  try {
+    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}/projects/${encodeURIComponent(slug)}/deploy-status`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body?.stages ?? null;
+  } catch {
+    return null;
+  }
+}
 async function fetchOrgConfig(deps) {
   if (!deps.baseUrl) return null;
   const token = await deps.token();
@@ -5741,6 +5830,173 @@ async function upsertProject(slug, patch, deps) {
   return postJson(`/projects/${encodeURIComponent(slug)}`, patch, deps);
 }
 
+// src/project-readiness.ts
+var STAGES = ["dev", "rc", "main"];
+var DEFAULT_RUNTIME_SECRET_NAMES = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
+function slugOfRepo(repoOrSlug) {
+  return (repoOrSlug.includes("/") ? repoOrSlug.split("/").pop() : repoOrSlug).toLowerCase();
+}
+function repoFrom(repoOrSlug, slug) {
+  return repoOrSlug.includes("/") ? repoOrSlug : `mutmutco/${slug}`;
+}
+function defaultSubdomain(slug) {
+  return slug.replace(/^[a-z]+-/, "");
+}
+function defaultDeployModel(meta, repo) {
+  if (meta?.deployModel) return meta.deployModel;
+  if (meta?.class === "content") return "content";
+  if (repo.toLowerCase().endsWith("/mmi-hub")) return "hub-serverless";
+  return "tenant-container";
+}
+function stageRequiredSecrets(stage2, meta) {
+  const contract = meta.requiredRuntimeSecrets;
+  const extra = Array.isArray(contract) ? contract : Array.isArray(contract?.[stage2]) ? contract[stage2] ?? [] : [];
+  return [.../* @__PURE__ */ new Set([...DEFAULT_RUNTIME_SECRET_NAMES, ...extra])];
+}
+function stageKey(stage2, key) {
+  return key.includes("/") ? key : `${stage2}/${key}`;
+}
+function appGapsFor(meta, model, slug) {
+  if (model === "content") return ["Content repo: keep app-owned work to docs/content changes; release train does not apply."];
+  const gaps = [
+    "Ensure Docker/compose runs from the central release directory and consumes the Hub-generated .env.",
+    "Make app config fail clearly for missing required env in prod/rc instead of relying on hidden defaults.",
+    "Keep app-owned README.md and architecture.md aligned with v2 central deploy/secrets reality."
+  ];
+  if (slug === "mmi-katip") {
+    gaps.push("Katip-specific app plan: declare Google Workspace env requirements, remove prod-hidden impersonation defaults, and make non-critical Google Workspace failures degrade instead of crash-looping.");
+  }
+  if (!meta) gaps.unshift("No app-owned repo changes can be planned precisely until Hub registry META exists.");
+  return gaps;
+}
+function contractByStage(contract) {
+  if (Array.isArray(contract)) return { dev: contract, rc: contract, main: contract };
+  return contract ?? {};
+}
+function ensureStageNames(names, required) {
+  return [.../* @__PURE__ */ new Set([...names ?? [], ...required])];
+}
+function sameNames(a, b) {
+  const left = new Set(a ?? []);
+  const right = new Set(b ?? []);
+  if (left.size !== right.size) return false;
+  return [...left].every((name) => right.has(name));
+}
+function sameStageContract(a, b) {
+  return STAGES.every((stage2) => sameNames(a[stage2], b[stage2]));
+}
+function buildV2HealPatch(repoOrSlug, meta) {
+  const slug = slugOfRepo(repoOrSlug);
+  const repo = repoFrom(repoOrSlug, slug);
+  const sub = defaultSubdomain(slug);
+  const patch = {};
+  const model = defaultDeployModel(meta, repo);
+  if (!meta?.class) patch.class = "deployable";
+  if (!meta?.deployModel) patch.deployModel = model;
+  if (!meta?.vaultPath) patch.vaultPath = `/mmi-future/${slug}`;
+  if (!meta?.kbPointer) patch.kbPointer = `kb/projects/${slug}.md`;
+  if (!meta?.oauth) patch.oauth = { subdomains: [sub], callbackPath: "/auth/callback" };
+  if (!meta?.edgeDomains && model === "tenant-container") {
+    patch.edgeDomains = {
+      dev: `dev.${sub}.mutatismutandis.co`,
+      rc: `rc.${sub}.mutatismutandis.co`,
+      main: `${sub}.mutatismutandis.co`
+    };
+  }
+  if (slug === "mmi-katip") {
+    const required = ["GOOGLE_IMPERSONATE_USER", "GOOGLE_ADMIN_USER"];
+    const current = contractByStage(meta?.requiredRuntimeSecrets);
+    const next = {
+      dev: ensureStageNames(current.dev, required),
+      rc: ensureStageNames(current.rc, required),
+      main: ensureStageNames(current.main, required)
+    };
+    if (!sameStageContract(current, next)) {
+      patch.requiredRuntimeSecrets = next;
+    }
+  }
+  return { slug, patch, appOwnedGaps: appGapsFor(meta, model, slug) };
+}
+async function buildV2Doctor(repoOrSlug, deps) {
+  const slug = slugOfRepo(repoOrSlug);
+  const repo = repoFrom(repoOrSlug, slug);
+  const meta = await deps.getProject(slug);
+  const model = defaultDeployModel(meta, repo);
+  const autoHeal = buildV2HealPatch(repo, meta);
+  if (!meta) {
+    const emptySecrets = {
+      dev: { required: [], present: [], missing: [] },
+      rc: { required: [], present: [], missing: [] },
+      main: { required: [], present: [], missing: [] }
+    };
+    const emptyCoords = {
+      dev: { ok: false },
+      rc: { ok: false },
+      main: { ok: false }
+    };
+    return {
+      ok: false,
+      repo,
+      slug,
+      hubOwned: { meta: { ok: false, missing: [`PROJECT#${slug}/META`] }, deployCoords: emptyCoords, secrets: emptySecrets },
+      autoHealAvailable: Object.keys(autoHeal.patch),
+      appOwnedGaps: autoHeal.appOwnedGaps
+    };
+  }
+  const presentSecrets = new Set(await deps.listSecrets(repo));
+  const deployCoords = Object.fromEntries(await Promise.all(STAGES.map(async (stage2) => [stage2, { ok: await deps.hasDeployCoords(slug, stage2) }])));
+  const secrets2 = Object.fromEntries(STAGES.map((stage2) => {
+    const required = stageRequiredSecrets(stage2, meta).map((key) => stageKey(stage2, key));
+    const present = required.filter((key) => presentSecrets.has(key));
+    const missing = required.filter((key) => !presentSecrets.has(key));
+    return [stage2, { required, present, missing }];
+  }));
+  const metaMissing = ["class", "deployModel", "vaultPath", "kbPointer", "oauth"].filter((key) => meta[key] === void 0);
+  const ok = metaMissing.length === 0 && Object.values(deployCoords).every((v) => v.ok) && Object.values(secrets2).every((v) => v.missing.length === 0);
+  return {
+    ok,
+    repo,
+    slug,
+    class: meta.class,
+    deployModel: model,
+    hubOwned: { meta: { ok: metaMissing.length === 0, missing: metaMissing }, deployCoords, secrets: secrets2 },
+    autoHealAvailable: Object.keys(autoHeal.patch),
+    appOwnedGaps: autoHeal.appOwnedGaps
+  };
+}
+function renderReadinessIssueBody(existingBody, report, opts = {}) {
+  const start = "<!-- mmi-v2-readiness:start -->";
+  const end = "<!-- mmi-v2-readiness:end -->";
+  const stageLines = STAGES.map((stage2) => {
+    const coords = report.hubOwned.deployCoords[stage2].ok ? "coords ok" : "coords missing/unverified";
+    const missing = report.hubOwned.secrets[stage2].missing;
+    return `- ${stage2}: ${coords}; ${missing.length ? `missing ${missing.join(", ")}` : "required secret names present"}`;
+  });
+  const section = [
+    start,
+    "## Hub v2 readiness",
+    "",
+    `Repo: ${report.repo}`,
+    `Deploy model: ${report.deployModel ?? "(unresolved)"}`,
+    `Overall: ${report.ok ? "ready" : "not ready"}`,
+    "",
+    "### Hub-owned diagnosis",
+    `- META: ${report.hubOwned.meta.ok ? "ok" : `missing ${report.hubOwned.meta.missing.join(", ")}`}`,
+    ...stageLines,
+    "",
+    "### Auto-heal applied / available",
+    ...opts.healed?.length ? opts.healed.map((x) => `- ${x}`) : report.autoHealAvailable.map((x) => `- ${x}`),
+    "",
+    "### App-owned implementation plan",
+    ...report.appOwnedGaps.map((x) => `- ${x}`),
+    end
+  ].join("\n");
+  const re = new RegExp(`${start}[\\s\\S]*?${end}`);
+  return re.test(existingBody) ? existingBody.replace(re, section) : `${existingBody.trim()}
+
+${section}`.trim();
+}
+
 // src/kb.ts
 var DEFAULT_KB = { owner: "mutmutco", repo: "MM-KB", ref: "main" };
 function resolveKbSource(rawBase) {
@@ -5887,7 +6143,8 @@ async function planPull(deps, slug, opts = {}) {
   deps.log(`pulled ${slug} \u2192 ${planPath(slug)}`);
 }
 async function planList(deps, opts = {}) {
-  const qs = opts.project ? `?${new URLSearchParams({ project: opts.project }).toString()}` : "";
+  const project2 = opts.project ?? (opts.quiet ? await deps.project() : void 0);
+  const qs = project2 ? `?${new URLSearchParams({ project: project2 }).toString()}` : "";
   let res;
   try {
     res = await deps.fetch(`${deps.apiUrl}/plan/list${qs}`, {
@@ -6063,15 +6320,15 @@ async function secretsList(deps, opts) {
   const { secrets: secrets2 } = await res.json();
   deps.log(formatSecretList(secrets2 ?? []));
 }
-var DEFAULT_RUNTIME_SECRET_NAMES = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
+var DEFAULT_RUNTIME_SECRET_NAMES2 = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
 function stringList(v) {
   return Array.isArray(v) ? v.filter((x) => typeof x === "string" && isValidSecretKey(x)) : [];
 }
 function requiredRuntimeSecretNames(stage2, contract) {
   const extra = Array.isArray(contract) ? stringList(contract) : stringList(contract?.[stage2]);
-  return [.../* @__PURE__ */ new Set([...DEFAULT_RUNTIME_SECRET_NAMES, ...extra])];
+  return [.../* @__PURE__ */ new Set([...DEFAULT_RUNTIME_SECRET_NAMES2, ...extra])];
 }
-function stageKey(stage2, key) {
+function stageKey2(stage2, key) {
   return key.includes("/") ? key : `${stage2}/${key}`;
 }
 async function secretsPreflight(deps, opts) {
@@ -6094,7 +6351,7 @@ async function secretsPreflight(deps, opts) {
   }
   const { secrets: secrets2 } = await res.json();
   const present = new Set((secrets2 ?? []).map((s) => s.key));
-  const required = opts.required.map((key) => stageKey(opts.stage, key));
+  const required = opts.required.map((key) => stageKey2(opts.stage, key));
   const missing = required.filter((key) => !present.has(key));
   if (missing.length) {
     deps.log(`missing ${missing.join(", ")}`);
@@ -6218,7 +6475,7 @@ var LOOPBACK = ["http://localhost", "http://127.0.0.1"];
 var SSM_ENVS = ["dev", "rc", "main"];
 var SSM_NAMES = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
 var uniq = (xs) => [...new Set(xs)];
-function defaultSubdomain(slug) {
+function defaultSubdomain2(slug) {
   const i = slug.indexOf("-");
   return i === -1 ? slug : slug.slice(i + 1);
 }
@@ -6247,7 +6504,7 @@ function oauthSsmKeys() {
 }
 function parseOauthConfig(mmiConfig, slug) {
   const raw = mmiConfig?.oauth ?? {};
-  const subdomains = Array.isArray(raw.subdomains) && raw.subdomains.length > 0 ? raw.subdomains.map(String) : [defaultSubdomain(slug)];
+  const subdomains = Array.isArray(raw.subdomains) && raw.subdomains.length > 0 ? raw.subdomains.map(String) : [defaultSubdomain2(slug)];
   const domains = Array.isArray(raw.domains) && raw.domains.length > 0 ? raw.domains.map(String) : [...DEFAULT_DOMAINS];
   const callbackPath = typeof raw.callbackPath === "string" && raw.callbackPath ? raw.callbackPath : DEFAULT_CALLBACK_PATH;
   if (!callbackPath.startsWith("/")) {
@@ -6407,7 +6664,15 @@ async function postCapture(capture, quiet = false) {
       // duplicate the note. Backend capture-latency root cause tracked in #255.
       signal: AbortSignal.timeout(2e4)
     });
-    if (!quiet) console.log(res.ok ? "noted" : `saga: HTTP ${res.status}`);
+    let message = "";
+    if (!res.ok) {
+      try {
+        const body = await res.clone().json();
+        message = typeof body.message === "string" ? body.message : "";
+      } catch {
+      }
+    }
+    if (!quiet) console.log(res.ok ? "noted" : formatCaptureFailure(res.status, message));
   } catch (e) {
     if (!quiet) console.error(`mmi-cli saga: ${e.message}`);
   }
@@ -6469,34 +6734,6 @@ async function applyGcPlan(plan2, remote) {
     await execFileP3("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS });
   }
 }
-async function cleanupLocalBranch(branch, before = {}) {
-  const result = { branchDeleted: false };
-  if (!branch) return result;
-  const { stdout } = await execFileP3("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
-  const afterWorktrees = parseWorktreePorcelain(stdout);
-  const wtPath = selectPrMergeCleanupWorktree(branch, before.worktrees ?? [], afterWorktrees, before.startingPath);
-  const safeCwd = selectSafeWorktreeCwd([...afterWorktrees, ...before.worktrees ?? []], wtPath);
-  const git = (args) => safeCwd ? execFileP3("git", ["-C", safeCwd, ...args], { timeout: GIT_TIMEOUT_MS }) : execFileP3("git", args, { timeout: GIT_TIMEOUT_MS });
-  if (wtPath) {
-    await git(["worktree", "remove", "--force", wtPath]).catch(() => {
-    });
-    result.worktreeRemoved = wtPath;
-  }
-  const current = safeCwd ? ((await git(["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => ({ stdout: "" }))).stdout || "").trim() : await gitOut(["rev-parse", "--abbrev-ref", "HEAD"]) || "";
-  if (branch !== current) {
-    await git(["branch", "-D", branch]).then(() => {
-      result.branchDeleted = true;
-    }).catch(() => {
-    });
-    if (!result.branchDeleted) {
-      const remaining = await git(["branch", "--list", branch]).catch(() => ({ stdout: "" }));
-      result.branchDeleted = branchMissingFromList(branch, remaining.stdout || "");
-    }
-  }
-  if (wtPath) await git(["worktree", "prune"]).catch(() => {
-  });
-  return result;
-}
 function resolveVersion() {
   try {
     const manifest = (0, import_node_path4.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
@@ -6542,39 +6779,41 @@ async function applyVersionAutoUpdate(report, log) {
     }
   }
   try {
-    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
     log(`  \u21BB updating mmi-cli ${report.currentVersion} \u2192 ${target}\u2026`);
-    await execFileP3(npm, ["install", "-g", "@mutmutco/cli@latest"], { timeout: NPM_UPDATE_TIMEOUT_MS });
+    await runHostBin("npm", ["install", "-g", "@mutmutco/cli@latest"], { timeout: NPM_UPDATE_TIMEOUT_MS });
     return { ...report, ok: true };
   } catch {
     return report;
   }
 }
-var CLAUDE_PLUGIN_TIMEOUT_MS = 6e4;
+async function requireFreshTrainCli(commandName) {
+  const report = buildVersionLagReport({
+    currentVersion: resolveVersion(),
+    repoVersion: readRepoVersion(),
+    releasedVersion: await fetchReleasedVersion()
+  });
+  if (report.ok) return;
+  const target = report.staleAgainst === "released" ? `released ${report.releasedVersion}` : `repo ${report.repoVersion}`;
+  throw new Error(`running mmi-cli ${report.currentVersion} is stale against ${target}; run doctor/update first so ${commandName} uses the current train path`);
+}
+var CLAUDE_PLUGIN_TIMEOUT_MS = 12e4;
+function runHostBin(bin, args, opts) {
+  return isWin ? execFileP3("cmd.exe", ["/c", bin, ...args], opts) : execFileP3(bin, args, opts);
+}
 async function runClaudePlugin(args) {
-  const candidates = isWin ? ["claude.cmd", "claude.exe", "claude"] : ["claude"];
-  for (const bin of candidates) {
-    try {
-      await execFileP3(bin, args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
-      return true;
-    } catch (err) {
-      if (err.code === "ENOENT") continue;
-      return false;
-    }
+  try {
+    await runHostBin("claude", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
+    return true;
+  } catch {
+    return false;
   }
-  return false;
 }
 async function applyClaudePluginHeal(surface, log) {
   if (surface !== "claude-cli" && surface !== "claude-vscode") return false;
   log("  \u21BB updating the MMI plugin via `claude plugin` (marketplace \u2192 update \u2192 enable)\u2026");
-  const steps = [
-    ["plugin", "marketplace", "update", "mmi"],
-    ["plugin", "update", "mmi@mmi"],
-    ["plugin", "enable", "mmi@mmi"]
-  ];
-  for (const step of steps) {
-    if (!await runClaudePlugin(step)) return false;
-  }
+  if (!await runClaudePlugin(["plugin", "marketplace", "update", "mmi"])) return false;
+  if (!await runClaudePlugin(["plugin", "update", "mmi@mmi"])) return false;
+  await runClaudePlugin(["plugin", "enable", "mmi@mmi"]);
   return true;
 }
 var program2 = new Command();
@@ -7030,6 +7269,47 @@ function reportWrite(label, res) {
   const detail = res.body?.error ?? "";
   fail(`${label}: HTTP ${res.status}${detail ? ` \u2014 ${detail}` : ""}`);
 }
+async function v2ReadinessDeps(cfg) {
+  const reg = registryClientDeps(cfg);
+  return {
+    getProject: (slug) => fetchProjectBySlug(slug, reg),
+    hasDeployCoords: async (slug, stage2) => {
+      const status = await fetchDeployStatusBySlug(slug, reg);
+      return Boolean(status?.[stage2]);
+    },
+    listSecrets: async (targetRepo2) => {
+      const apiUrl = cfg.sagaApiUrl;
+      if (!apiUrl) return [];
+      const qs = new URLSearchParams({ repo: targetRepo2 }).toString();
+      const res = await fetch(`${apiUrl.replace(/\/$/, "")}/secrets/list?${qs}`, {
+        method: "GET",
+        headers: await sagaHeaders(),
+        signal: AbortSignal.timeout(8e3)
+      });
+      if (!res.ok) return [];
+      const body = await res.json();
+      return (body.secrets ?? []).map((s) => s.key).filter(Boolean);
+    }
+  };
+}
+async function updateV2ReadinessIssue(repo, report, healed) {
+  const title = "v2 readiness: central deploy + secrets alignment";
+  const freshBody = renderReadinessIssueBody("", report, { healed });
+  const list = await execFileP3("gh", ["issue", "list", "--repo", repo, "--state", "open", "--search", "v2 readiness in:title", "--json", "number,title", "--limit", "20"], { timeout: 2e4 });
+  const issues = JSON.parse(list.stdout || "[]");
+  const existing = issues.find((i) => i.title.toLowerCase().includes("v2 readiness"));
+  if (!existing) {
+    const created = await execFileP3("gh", ["issue", "create", "--repo", repo, "--title", title, "--body", freshBody, "--label", "feature"], { timeout: 2e4 });
+    const url = created.stdout.trim();
+    const number = Number(url.match(/\/issues\/(\d+)$/)?.[1] ?? 0);
+    return { number, url, action: "created" };
+  }
+  const view = await execFileP3("gh", ["issue", "view", String(existing.number), "--repo", repo, "--json", "body,url", "--jq", "{body:.body,url:.url}"], { timeout: 2e4 });
+  const current = JSON.parse(view.stdout || "{}");
+  const nextBody = renderReadinessIssueBody(current.body ?? "", report, { healed });
+  await execFileP3("gh", ["issue", "edit", String(existing.number), "--repo", repo, "--body", nextBody], { timeout: 2e4 });
+  return { number: existing.number, url: current.url ?? `https://github.com/${repo}/issues/${existing.number}`, action: "updated" };
+}
 var project = program2.command("project").description("the DDB org registry \u2014 list/get projects (any member); set is master-only");
 project.command("list").description("list all projects (identity + board, never deploy coords)").option("--json", "machine-readable output").action(async (o) => {
   const cfg = await loadConfig();
@@ -7058,6 +7338,38 @@ project.command("resolve <owner/repo>").description("deploy coords for a stage \
   }
   fail(msg);
 });
+project.command("doctor <owner/repo>").description("diagnose Hub v2 readiness for a repo without reading product repo files").option("--v2", "run the v2 central deploy/secrets readiness contract").option("--json", "machine-readable output").action(async (repo, o) => {
+  if (!o.v2) return fail("project doctor: pass --v2");
+  const cfg = await loadConfig();
+  const report = await buildV2Doctor(repo, await v2ReadinessDeps(cfg));
+  console.log(JSON.stringify(report));
+  if (!report.ok) process.exitCode = 1;
+});
+project.command("heal <owner/repo>").description("repair Hub-owned v2 readiness state only; never product repo files").option("--v2", "run the v2 central deploy/secrets readiness contract").option("--apply", "apply the Hub-owned registry patch").option("--json", "machine-readable output").action(async (repo, o) => {
+  if (!o.v2) return fail("project heal: pass --v2");
+  const cfg = await loadConfig();
+  const slug = slugOf(repo);
+  const meta = await fetchProjectBySlug(slug, registryClientDeps(cfg));
+  const plan2 = buildV2HealPatch(repo, meta);
+  if (!o.apply) {
+    console.log(JSON.stringify({ ok: true, slug, dryRun: true, patch: plan2.patch, appOwnedGaps: plan2.appOwnedGaps }));
+    return;
+  }
+  if (!Object.keys(plan2.patch).length) {
+    console.log(JSON.stringify({ ok: true, slug, applied: [], appOwnedGaps: plan2.appOwnedGaps }));
+    return;
+  }
+  const res = await upsertProject(slug, plan2.patch, registryClientDeps(cfg));
+  if (!res.ok) return reportWrite("project heal", res);
+  console.log(JSON.stringify({ ok: true, slug, applied: Object.keys(plan2.patch), appOwnedGaps: plan2.appOwnedGaps, result: res.body }));
+});
+project.command("readiness <owner/repo>").description("update the repo v2 readiness issue with Hub diagnosis and app-owned tasks").option("--update-issue", "create/update the bounded v2 readiness issue section").option("--json", "machine-readable output").action(async (repo, o) => {
+  if (!o.updateIssue) return fail("project readiness: pass --update-issue");
+  const cfg = await loadConfig();
+  const report = await buildV2Doctor(repo, await v2ReadinessDeps(cfg));
+  const issue2 = await updateV2ReadinessIssue(repo, report, []);
+  console.log(JSON.stringify({ ok: true, repo, issue: issue2, ready: report.ok }));
+});
 project.command("set <owner/repo>").description("MASTER-ONLY: upsert a project META (idempotent merge; no clobber of unspecified fields)").option("--class <class>", "deployable | content").option("--deploy-model <model>", "hub-serverless | serverless | tenant-container | content (release-train deploy path, #514)").option("--var <KEY=VALUE...>", "META field to set (repeatable): name, division, projectId, branch, wikiRepo, vaultPath, kbPointer").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   const slug = slugOf(repoOrSlug);
@@ -7217,6 +7529,15 @@ pr.command("create").description("create a PR and print {number,url} JSON").requ
   const created = await ghCreate(buildPrArgs({ title: o.title, body: o.body, base: o.base, head: o.head, repo: o.repo }));
   console.log(JSON.stringify(created));
 });
+async function remoteBranchExists(branch) {
+  if (!branch) return void 0;
+  try {
+    const { stdout } = await execFileP3("git", ["ls-remote", "--heads", "origin", branch], { timeout: GIT_TIMEOUT_MS });
+    return stdout.trim().length > 0;
+  } catch {
+    return void 0;
+  }
+}
 pr.command("merge <number>").description("merge a PR (squash by default) and clean up its branch + worktree \u2014 no leftover local branch").option("--squash", "squash merge (default)").option("--merge", "create a merge commit").option("--rebase", "rebase merge").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(async (number, o) => {
   const method = o.rebase ? "--rebase" : o.merge ? "--merge" : "--squash";
   const repoArgs = o.repo ? ["--repo", o.repo] : [];
@@ -7225,11 +7546,42 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
   const beforeWorktrees = parseWorktreePorcelain(
     (await execFileP3("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS }).catch(() => ({ stdout: "" }))).stdout
   );
+  const remoteBefore = repoArgs.length ? void 0 : await remoteBranchExists(headRef);
+  let remoteDeleteAttempted = false;
+  let remoteNotAttemptedReason = repoArgs.length ? "repo-option" : void 0;
   await execFileP3("gh", ["pr", "merge", number, ...repoArgs, method, "--delete-branch"], { timeout: GC_GH_TIMEOUT_MS }).catch((e) => {
-    if (!/used by worktree|cannot delete branch|already been merged/i.test(String(e.message || ""))) throw e;
+    const message = String(e.message || "");
+    if (/already been merged/i.test(message)) {
+      remoteNotAttemptedReason = "pr-already-merged";
+      return;
+    }
+    if (!/used by worktree|cannot delete branch/i.test(message)) throw e;
+  });
+  if (!remoteNotAttemptedReason) remoteDeleteAttempted = true;
+  const remoteAfter = repoArgs.length ? void 0 : await remoteBranchExists(headRef);
+  const remoteBranch = buildRemoteBranchCleanupReport(headRef, {
+    attempted: remoteDeleteAttempted,
+    existedBefore: remoteBefore,
+    existsAfter: remoteAfter,
+    reason: remoteNotAttemptedReason
+  });
+  const localCleanup = repoArgs.length ? {
+    branch: headRef,
+    localBranch: { name: headRef, status: "not-attempted", reason: "repo-option" },
+    worktree: void 0
+  } : await cleanupPrMergeLocalBranch(headRef, {
+    beforeWorktrees,
+    startingPath,
+    execGit: async (args) => (await execFileP3("git", args, { timeout: GIT_TIMEOUT_MS })).stdout
   });
-  const cleaned = repoArgs.length ? { branchDeleted: false } : await cleanupLocalBranch(headRef, { worktrees: beforeWorktrees, startingPath });
-  console.log(JSON.stringify({ merged: number, branch: headRef, method: method.slice(2), ...cleaned }));
+  console.log(JSON.stringify({
+    merged: number,
+    branch: headRef,
+    method: method.slice(2),
+    remoteBranch,
+    localBranch: localCleanup.localBranch,
+    worktree: localCleanup.worktree
+  }));
 });
 async function runBoardRead(o) {
   try {
@@ -7427,6 +7779,11 @@ program2.command("stage-live").description("explain that remote rc/live environm
 });
 for (const commandName of ["rcand", "release", "hotfix"]) {
   program2.command(commandName).description(`plan ${commandName} train operations; mutations require explicit master-admin approval`).option("--json", "machine-readable output").option("--apply", commandName === "hotfix" ? "reserved; hotfix uses the /hotfix skill PR path" : "execute the guarded master-only train after explicit approval").action(async (o) => {
+    try {
+      await requireFreshTrainCli(commandName);
+    } catch (e) {
+      return fail(`${commandName}: ${e.message}`);
+    }
     if (o.apply) {
       if (commandName === "hotfix") return fail("hotfix: CLI apply is reserved; use the /hotfix skill PR path after explicit master-admin approval");
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "MMI Future CLI — delivers the org rules (whole-file), plus saga and KB access. The cross-IDE engine the plugin's SessionStart hook drives.",
   "type": "module",
   "license": "UNLICENSED",