@mutmutco/cli 2.5.1 → 2.7.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

@@ -3309,6 +3309,9 @@ function buildHealth(i) {
   if (!i.sagaApiUrl) problems.push("sagaApiUrl not configured in .mmi/config.json");
   if (!i.identity) problems.push("no GitHub identity (gh auth token / GH_TOKEN)");
   if (!i.reachable) problems.push("saga backend unreachable");
+  if (i.reachable && i.livenessStatus === 403 && i.livenessMessage === "Forbidden") {
+    problems.push("saga API route-level 403 from GitHubAuthorizer cache/policy");
+  }
   if (i.reachable && i.authorized === false) problems.push("saga backend rejected authenticated state access");
   if (!i.key.sessionId || i.key.sessionId === "-") problems.push("unsafe session id");
   const safeToWrite = problems.length === 0;
@@ -3317,6 +3320,8 @@ function buildHealth(i) {
     safeToWrite,
     identity: i.identity,
     reachable: i.reachable,
+    livenessStatus: i.livenessStatus,
+    livenessMessage: i.livenessMessage,
     authorized: i.authorized,
     sagaApiUrl: i.sagaApiUrl,
     key: i.key,
@@ -3336,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;
@@ -3367,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";
@@ -3598,6 +3608,36 @@ query($owner: String!, $number: Int!, $after: String) {
     }
   }
 }`;
+var ISSUE_PROJECT_ITEM_QUERY = `
+query($repoOwner: String!, $repoName: String!, $number: Int!) {
+  repository(owner: $repoOwner, name: $repoName) {
+    issue(number: $number) {
+      id
+      number
+      title
+      url
+      state
+      repository { nameWithOwner }
+      labels(first: 10) { nodes { name } }
+      assignees(first: 10) { nodes { login } }
+      projectItems(first: 20) {
+        nodes {
+          id
+          project { id title }
+          fieldValues(first: 8) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                name
+                optionId
+                field { ... on ProjectV2SingleSelectField { name } }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
 function resolveBoardConfig(cfg) {
   const missing = [];
   if (!cfg.projectOwner) missing.push("projectOwner");
@@ -3871,6 +3911,14 @@ async function claimBoardIssue(options, deps = {}) {
   const cfg = resolveBoardConfig(options.config);
   const gh = deps.gh ?? defaultGh;
   const collected = await collectBoardItems(cfg, { repo: options.repo, allowPartial: options.allowPartial }, deps);
+  const selector = parseIssueSelector(options.selector, collected.repo);
+  try {
+    findBoardItem(collected.items, selector);
+  } catch (e) {
+    const fallback = await fetchIssueProjectItem(gh, cfg, selector);
+    if (!fallback) throw e;
+    collected.items.push(fallback);
+  }
   const writable = await resolveWritableReposForClaimables(collected.items, gh, options.allowPartial ?? false);
   collected.warnings.push(...writable.warnings);
   collected.partial = collected.partial || writable.partial;
@@ -3882,7 +3930,6 @@ async function claimBoardIssue(options, deps = {}) {
     warnings: collected.warnings,
     partial: collected.partial
   };
-  const selector = parseIssueSelector(options.selector, collected.repo);
   const flatItem = findBoardItem(collected.items, selector);
   if (flatItem.status === "Todo" && flatItem.assignees.length === 0 && !writable.repos.has(flatItem.repository.toLowerCase())) {
     throw new Error(`${flatItem.ref} is not claimable: viewer does not have write access to ${flatItem.repository}`);
@@ -4039,6 +4086,42 @@ async function fetchProjectPage(gh, cfg, after) {
   if (!parsed.data) throw new Error("gh GraphQL response did not include data");
   return parsed.data;
 }
+async function fetchIssueProjectItem(gh, cfg, selector) {
+  const [repoOwner, repoName] = selector.repo.split("/");
+  if (!repoOwner || !repoName) return void 0;
+  const { stdout } = await gh([
+    "api",
+    "graphql",
+    "-f",
+    `query=${ISSUE_PROJECT_ITEM_QUERY}`,
+    "-f",
+    `repoOwner=${repoOwner}`,
+    "-f",
+    `repoName=${repoName}`,
+    "-F",
+    `number=${selector.number}`
+  ]);
+  const parsed = JSON.parse(stdout);
+  const issue2 = parsed.data?.repository?.issue;
+  if (!issue2) return void 0;
+  const projectItem = (issue2.projectItems?.nodes ?? []).find((item) => item.project?.id === cfg.projectId);
+  if (!projectItem) return void 0;
+  return nodeToItem({
+    id: projectItem.id,
+    fieldValues: projectItem.fieldValues,
+    content: {
+      __typename: "Issue",
+      id: issue2.id,
+      number: issue2.number,
+      title: issue2.title,
+      url: issue2.url,
+      state: issue2.state,
+      repository: issue2.repository,
+      labels: issue2.labels,
+      assignees: issue2.assignees
+    }
+  });
+}
 function nodesToItems(nodes, warnings) {
   const items = [];
   for (const node of nodes) {
@@ -4168,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();
@@ -4275,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");
@@ -4325,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") {
@@ -4336,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 }
     ];
   }
@@ -4505,8 +4654,13 @@ var PLUGIN_DRIFT_LABEL = "plugin config drift (mmi@mmi duplicate rows / stale gi
 function recordFreshness(r) {
   return r.lastUpdated ?? r.installedAt ?? "";
 }
-function freshestRecord(records) {
-  return records.reduce((best, r) => recordFreshness(r) > recordFreshness(best) ? r : best);
+function bestRecord(records) {
+  return records.reduce((best, r) => {
+    const byVersion = compareVersions(r.version ?? "0", best.version ?? "0");
+    if (byVersion > 0) return r;
+    if (byVersion < 0) return best;
+    return recordFreshness(r) > recordFreshness(best) ? r : best;
+  });
 }
 function pluginConfigDriftFix(pluginId) {
   return `\`${pluginId}\` registered as N duplicate project rows / a stale gitCommitSha in ~/.claude/plugins/installed_plugins.json \u2014 run \`mmi-cli doctor\` to collapse them to one \`scope: user\` entry at the highest version (a .bak backup is written first), or in \`/plugin\` uninstall the extra rows and reinstall once at user scope`;
@@ -4523,19 +4677,21 @@ function buildPluginConfigDriftCheck(input) {
   const records = input.installed?.plugins?.[pluginId];
   if (!Array.isArray(records) || records.length === 0) return base;
   const projectRows = records.filter((r) => r.scope === "project");
-  const freshest = freshestRecord(records);
-  const freshSha = freshest.gitCommitSha;
-  const staleShaRows = freshSha ? records.filter((r) => r.gitCommitSha !== void 0 && r.gitCommitSha !== freshSha).length : 0;
+  const best = bestRecord(records);
+  const bestSha = best.gitCommitSha;
+  const staleShaRows = bestSha ? records.filter((r) => r.gitCommitSha !== void 0 && r.gitCommitSha !== bestSha).length : 0;
+  const duplicateRows = records.length > 1 ? records.length : 0;
   const duplicateProjectRows = projectRows.length > 1 ? projectRows.length : 0;
-  if (duplicateProjectRows === 0 && staleShaRows === 0) {
-    return { ...base, duplicateProjectRows: 0, staleShaRows: 0 };
+  if (duplicateRows === 0 && staleShaRows === 0) {
+    return { ...base, duplicateRows: 0, duplicateProjectRows: 0, staleShaRows: 0 };
   }
-  const { projectPath: _drop, ...rest } = freshest;
+  const { projectPath: _drop, ...rest } = best;
   const collapsed = { ...rest, scope: "user" };
   return {
     ...base,
     ok: false,
     recordsToWrite: [collapsed],
+    duplicateRows,
     duplicateProjectRows,
     staleShaRows
   };
@@ -4549,6 +4705,58 @@ function buildGitignoreManagedBlockCheck(input) {
   if (!changed) return base;
   return { ...base, ok: false, contentToWrite: content };
 }
+function detectSurface(env) {
+  const has = (k) => Boolean(env[k]?.trim());
+  if (env.MMI_AGENT_SURFACE === "codex" || has("CODEX_HOME") || (env.CLAUDE_PLUGIN_ROOT ?? "").includes(".codex")) {
+    return "codex";
+  }
+  const isClaude = has("CLAUDECODE") || has("CLAUDE_CODE_ENTRYPOINT") || has("CLAUDE_PLUGIN_ROOT") || env.MMI_AGENT_SURFACE === "claude";
+  const isVscode = env.TERM_PROGRAM === "vscode" || has("VSCODE_PID") || has("VSCODE_GIT_ASKPASS_NODE");
+  if (isClaude && isVscode) return "claude-vscode";
+  if (isClaude) return "claude-cli";
+  return "shell";
+}
+function pluginRecoveryFix(surface) {
+  const claude = "claude plugin marketplace update mmi && claude plugin update mmi@mmi && claude plugin enable mmi@mmi";
+  switch (surface) {
+    case "claude-vscode":
+      return `${claude}   # then reopen the VS Code workspace to reload MMI commands`;
+    case "claude-cli":
+      return `${claude}   # then restart Claude Code, or run /reload-plugins`;
+    case "codex":
+      return "codex plugin marketplace upgrade mmi && codex plugin add mmi@mmi   # then restart Codex";
+    case "shell":
+    default:
+      return "npm install -g @mutmutco/cli@latest";
+  }
+}
+var INSTALLED_PLUGIN_VERSION_LABEL = "installed MMI plugin version (vs latest release)";
+function isSemverVersion(v) {
+  return typeof v === "string" && /^v?\d+\.\d+\.\d+/.test(v.trim());
+}
+function buildInstalledPluginVersionCheck(input) {
+  const pluginId = input.pluginId ?? MMI_PLUGIN_ID;
+  const base = {
+    ok: true,
+    label: INSTALLED_PLUGIN_VERSION_LABEL,
+    fix: pluginRecoveryFix(input.surface),
+    pluginId
+  };
+  if (!input.isOrgRepo) return base;
+  const records = input.installed?.plugins?.[pluginId];
+  if (!Array.isArray(records) || records.length === 0) return base;
+  const installedVersion = bestRecord(records).version;
+  if (!isSemverVersion(installedVersion) || !isSemverVersion(input.releasedVersion)) return base;
+  if (compareVersions(installedVersion, input.releasedVersion) >= 0) {
+    return { ...base, installedVersion, releasedVersion: input.releasedVersion };
+  }
+  return {
+    ...base,
+    ok: false,
+    installedVersion,
+    releasedVersion: input.releasedVersion
+  };
+}
 
 // src/stage-runner.ts
 var import_node_child_process3 = require("node:child_process");
@@ -5558,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();
@@ -5604,6 +5830,164 @@ 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 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 (JSON.stringify(current) !== JSON.stringify(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) {
@@ -5750,7 +6134,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}`, {
@@ -5926,15 +6311,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) {
@@ -5957,7 +6342,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(", ")}`);
@@ -6081,7 +6466,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);
 }
@@ -6110,7 +6495,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("/")) {
@@ -6270,7 +6655,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}`);
   }
@@ -6332,34 +6725,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");
@@ -6405,14 +6770,43 @@ 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;
   }
 }
+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) {
+  try {
+    await runHostBin("claude", args, { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
+    return true;
+  } catch {
+    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");
+  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();
 program2.name("mmi-cli").description("MMI Future CLI \u2014 org rules delivery, saga, KB. The engine the plugin SessionStart hook drives.").version(resolveVersion());
 var rules = program2.command("rules").description("org rules delivery");
@@ -6554,9 +6948,15 @@ saga.command("key").option("--json", "machine-readable output").description("pri
 async function probeBackend(url) {
   try {
     const res = await fetch(`${url}/saga/head`, { headers: await sagaHeaders(), signal: AbortSignal.timeout(8e3) });
-    return res.ok;
+    let message = "";
+    try {
+      const body = await res.clone().json();
+      message = typeof body.message === "string" ? body.message : "";
+    } catch {
+    }
+    return { reachable: res.ok || res.status === 403, status: res.status, message };
   } catch {
-    return false;
+    return { reachable: false };
   }
 }
 async function probeSagaAccess(url, key) {
@@ -6574,9 +6974,18 @@ saga.command("health").option("--json", "machine-readable output").option("--ban
   const key = await sagaKey(cfg, session);
   const source = session.source;
   const identity = await githubLogin();
-  const reachable = cfg.sagaApiUrl ? await probeBackend(cfg.sagaApiUrl) : false;
-  const authorized = cfg.sagaApiUrl && reachable ? await probeSagaAccess(cfg.sagaApiUrl, key) : void 0;
-  const report = buildHealth({ key, source, identity, reachable, authorized, sagaApiUrl: cfg.sagaApiUrl });
+  const liveness = cfg.sagaApiUrl ? await probeBackend(cfg.sagaApiUrl) : { reachable: false };
+  const authorized = cfg.sagaApiUrl && liveness.reachable ? await probeSagaAccess(cfg.sagaApiUrl, key) : void 0;
+  const report = buildHealth({
+    key,
+    source,
+    identity,
+    reachable: liveness.reachable,
+    livenessStatus: liveness.status,
+    livenessMessage: liveness.message,
+    authorized,
+    sagaApiUrl: cfg.sagaApiUrl
+  });
   if (o.json) return console.log(JSON.stringify(report));
   if (o.banner) {
     const banner = healthBanner(report);
@@ -6851,6 +7260,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();
@@ -6879,6 +7329,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);
@@ -7038,6 +7520,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] : [];
@@ -7046,11 +7537,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 cleaned = repoArgs.length ? { branchDeleted: false } : await cleanupLocalBranch(headRef, { worktrees: beforeWorktrees, startingPath });
-  console.log(JSON.stringify({ merged: number, branch: headRef, method: method.slice(2), ...cleaned }));
+  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
+  });
+  console.log(JSON.stringify({
+    merged: number,
+    branch: headRef,
+    method: method.slice(2),
+    remoteBranch,
+    localBranch: localCleanup.localBranch,
+    worktree: localCleanup.worktree
+  }));
 });
 async function runBoardRead(o) {
   try {
@@ -7248,6 +7770,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 {
@@ -7489,7 +8016,7 @@ function writeGitignore(content) {
     return false;
   }
 }
-program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone, plugin install record, .gitignore managed block, plugin config drift) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--guide", "print the MMI Agentic Onboarding guide URL").option("--json", "machine-readable output").action(async (opts) => {
+program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone, plugin install record, .gitignore managed block, plugin config drift, installed plugin version) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--guide", "print the MMI Agentic Onboarding guide URL").option("--json", "machine-readable output").action(async (opts) => {
   if (opts.guide) {
     if (opts.json) console.log(JSON.stringify({ resources: [MMI_AGENTIC_ONBOARDING_GUIDE] }, null, 2));
     else console.log(MMI_AGENTIC_ONBOARDING_GUIDE.url);
@@ -7517,12 +8044,15 @@ program2.command("doctor").description("check onboarding gates (GitHub auth, mmi
     if (root && (0, import_node_fs4.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
   }
   checks.push({ ok: onPath, label: "mmi-cli on PATH", fix: "auto-provisioned at session start \u2014 reopen the session, or install the MMI plugin" });
+  const surface = detectSurface(process.env);
+  const releasedVersion = await fetchReleasedVersion();
   let versionReport = buildVersionLagReport({
     currentVersion: resolveVersion(),
     repoVersion: readRepoVersion(),
-    releasedVersion: await fetchReleasedVersion()
+    releasedVersion
   });
   if (!opts.json) versionReport = await applyVersionAutoUpdate(versionReport, (m) => console.error(m));
+  if (!versionReport.ok) versionReport = { ...versionReport, fix: pluginRecoveryFix(surface) };
   checks.push(versionReport);
   const cfg = await loadConfig();
   checks.push({ ok: Boolean(cfg.sagaApiUrl), label: "repo config (.mmi/config.json)", fix: "ask a master-admin to run /bootstrap on this repo" });
@@ -7574,7 +8104,30 @@ program2.command("doctor").description("check onboarding gates (GitHub auth, mmi
       if (!opts.banner) console.error("  \u21BB repaired: collapsed mmi@mmi to one user-scope entry (backup at installed_plugins.json.bak) \u2014 run /reload-plugins");
     }
   }
+  if (!driftCheck.ok) driftCheck = { ...driftCheck, fix: pluginRecoveryFix(surface) };
   checks.push(driftCheck);
+  let installedVersionCheck = buildInstalledPluginVersionCheck({
+    isOrgRepo: Boolean(cfg.sagaApiUrl),
+    installed,
+    releasedVersion,
+    surface
+  });
+  if (!installedVersionCheck.ok && !opts.json) {
+    if (await applyClaudePluginHeal(surface, (m) => console.error(m))) {
+      const healed = buildInstalledPluginVersionCheck({
+        isOrgRepo: Boolean(cfg.sagaApiUrl),
+        installed: readInstalledPlugins(),
+        releasedVersion,
+        surface
+      });
+      installedVersionCheck = healed;
+      if (healed.ok && !opts.banner) {
+        const reload = surface === "claude-vscode" ? "reopen the VS Code workspace" : "restart Claude Code (or run /reload-plugins)";
+        console.error(`  \u21BB updated MMI plugin \u2192 ${releasedVersion ?? "latest"} via claude plugin \u2014 ${reload} to load the new commands`);
+      }
+    }
+  }
+  checks.push(installedVersionCheck);
   const gaps = checks.filter((c) => !c.ok);
   const resources = doctorResourcesForGaps(gaps);
   if (opts.json) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "2.5.1",
+  "version": "2.7.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",