@mutmutco/cli 2.52.1 → 2.53.0

package/dist/main.cjs

@@ -5174,12 +5174,13 @@ async function completeMainRelease(deps, ctx, meta, deployModel, watch, options,
   const announceNote = deps.announce ? (await deps.announce({ repo: ctx.repo, tag, summaryFile: options.announceSummaryFile })).note : void 0;
   const autoRunSince = (deps.now ?? Date.now)();
   const deployDispatch = await dispatchDeploy(deps, ctx, "main", "main", deployModel, watch, autoRunSince, releaseSha, "report", meta.publishDir);
-  const publishDispatch = deployDispatch.deployStatus === "failure" ? null : await dispatchPublishIfRequired(deps, ctx, meta, deployModel, "main", tag, watch, "report");
+  const publishDispatch = deployDispatch.deployStatus === "success" ? await dispatchPublishIfRequired(deps, ctx, meta, deployModel, "main", tag, watch, "report") : null;
   let dispatch = appendPublishDispatch(deployDispatch, publishDispatch);
-  if (!publishDispatch && deployDispatch.deployStatus === "failure" && meta.publishRequired && (deployModel === "tenant-container" || deployModel === "solo-container")) {
+  if (!publishDispatch && deployDispatch.deployStatus !== "success" && meta.publishRequired && (deployModel === "tenant-container" || deployModel === "solo-container")) {
+    const reason = deployDispatch.deployStatus === "failure" ? "box deploy failed \u2014 redeploy the box before publishing" : "box deploy not confirmed (run with --watch) \u2014 publish after the box deploy lands";
     dispatch = {
       ...dispatch,
-      note: `${dispatch.note}; tenant-publish.yml skipped (box deploy failed \u2014 redeploy the box before publishing)`
+      note: `${dispatch.note}; tenant-publish.yml skipped (${reason})`
     };
   }
   return { checks, releaseUrl, announceNote, dispatch };
@@ -6084,18 +6085,23 @@ function headPrompt(state) {
   const decisions = shownDecisions(state.decisions);
   const actions = (state.actionLog ?? []).slice(-HEAD_PROMPT_ACTION_LIMIT);
   return [
-    "You maintain ONE durable slot of a work-session: PINNED (things worth remembering). Given the CURRENT",
-    "HEAD and the recent TRANSCRIPT + DECISIONS, return an updated PINNED only. Keep it tight and concrete;",
-    "keep anything the user pinned; never invent; preserve Turkish characters (\xE7 \u011F \u0131 \u0130 \xF6 \u015F \xFC) exactly. Do",
-    "NOT manage next or the checklist \u2014 the note path owns those. The ANCHOR is the read-only North-Star \u2014",
-    "NEVER change it. Never restate an unverified artifact-claim (a named file, PR, flag, or board state)",
-    "as settled fact \u2014 keep it as the belief it was recorded as.",
+    "You maintain two durable slots of a work-session: PINNED (things worth remembering) and a NEXT",
+    "SUGGESTION (a best-effort one-line hint for the next useful step). Given the CURRENT HEAD and the",
+    "recent TRANSCRIPT + DECISIONS, return an updated PINNED and, optionally, a next suggestion. Keep",
+    "PINNED tight and concrete; keep anything the user pinned; never invent; preserve Turkish characters",
+    "(\xE7 \u011F \u0131 \u0130 \xF6 \u015F \xFC) exactly. Do NOT manage the checklist \u2014 the note path owns that. The ANCHOR is the",
+    "read-only North-Star \u2014 NEVER change it. Never restate an unverified artifact-claim (a named file,",
+    "PR, flag, or board state) as settled fact \u2014 keep it as the belief it was recorded as.",
     "You MAY also propose supersessions: each DECISION is shown with its original stable 0-based index. Propose a",
     "supersession ONLY for a NEWER decision that directly contradicts/replaces an OLDER one where neither",
     "already carries a supersededBy. HIGH PRECISION \u2014 propose ONLY when you are confident the older claim",
     "is now false or obsolete; the newer decision's timestamp MUST be later than the older's (newer-supersedes-",
-    "older only, never the reverse). When unsure, propose nothing. NEVER touch the anchor, next, or checklist.",
-    'Output ONLY a JSON object: {"pinned":[string],"supersede":[{"older":int,"newer":int,"reason":string}]}.',
+    "older only, never the reverse). When unsure, propose nothing. NEVER touch the anchor or checklist.",
+    'For "next": propose a single concise actionable line (\u2264140 chars) describing the most useful next step',
+    "for a future session, derived from the transcript. This is a best-effort suggestion shown only when",
+    "the user has not set their own NEXT. Use an empty string if nothing concrete emerges \u2014 never invent.",
+    "Preserve Turkish characters exactly.",
+    'Output ONLY a JSON object: {"pinned":[string],"next":string,"supersede":[{"older":int,"newer":int,"reason":string}]}.',
     "",
     "CURRENT HEAD:",
     JSON.stringify(state.head ?? {}, null, 2),
@@ -6119,6 +6125,9 @@ function parseHeadUpdate(raw) {
   if (!obj || typeof obj !== "object") return null;
   const u = {};
   if (Array.isArray(obj.pinned)) u.pinned = obj.pinned.filter((x) => typeof x === "string");
+  if (typeof obj.next === "string" && obj.next.trim()) {
+    u.nextAuto = obj.next.trim().slice(0, 280);
+  }
   if (Array.isArray(obj.supersede)) {
     const supersede = obj.supersede.filter((e) => {
       if (!e || typeof e !== "object") return false;
@@ -7365,6 +7374,18 @@ function writeState(path2, state) {
   mkdirFor(path2);
   (0, import_node_fs9.writeFileSync)(path2, JSON.stringify(state, null, 2), "utf8");
 }
+function writeStagePortReservation(port, cwd, statePath, globalStatePath, now) {
+  const reservation = {
+    pid: 0,
+    command: "",
+    cwd,
+    statePath,
+    startedAt: now().toISOString(),
+    port
+  };
+  writeState(statePath, reservation);
+  if (globalStatePath && globalStatePath !== statePath) writeState(globalStatePath, reservation);
+}
 async function cleanupStageState(state, paths, timeoutMs, fallbackCwd) {
   await killTree(state.pid);
   if (state.teardown?.command.trim()) {
@@ -7505,6 +7526,8 @@ async function runStage(config = {}, opts = {}) {
   if (problems.length) throw new Error(problems.join("; "));
   const cwd = opts.cwd ?? process.cwd();
   const timeoutMs = opts.timeoutMs ?? 6e4;
+  const statePath = opts.statePath ?? stageStatePath(cwd);
+  const globalStatePath = await resolveGlobalStatePath(cwd, opts.globalStatePath);
   const portGuard = resolveStagePortGuard(opts);
   await stopStage({ ...opts, cwd, requiredIdentityCwd: opts.requiredIdentityCwd ?? cwd });
   const reserved = await reservedPortsForWorktree(cwd);
@@ -7515,11 +7538,20 @@ async function runStage(config = {}, opts = {}) {
     stagePort = await resolveStagePort(config, portGuard, reserved);
   }
   const sub = (s) => substituteStagePort(s, stagePort);
-  await ensureStageRuntimeEnv(config, opts, cwd);
+  if (stagePort != null) {
+    writeStagePortReservation(stagePort, cwd, statePath, globalStatePath, opts.now ?? (() => /* @__PURE__ */ new Date()));
+  }
   const extraEnv = stageExtraEnv(config, stagePort);
   const build2 = config.build?.trim();
   const ranBuild = Boolean(build2);
-  if (build2) await shell(sub(build2), cwd, timeoutMs, stageProcessEnv(stagePort, extraEnv));
+  try {
+    await ensureStageRuntimeEnv(config, opts, cwd);
+    if (build2) await shell(sub(build2), cwd, timeoutMs, stageProcessEnv(stagePort, extraEnv));
+  } catch (e) {
+    (0, import_node_fs9.rmSync)(statePath, { force: true });
+    if (globalStatePath && globalStatePath !== statePath) (0, import_node_fs9.rmSync)(globalStatePath, { force: true });
+    throw e;
+  }
   const started = await startStage(config, {
     ...opts,
     cwd,
@@ -8519,15 +8551,28 @@ function planDirtyForAutosave(localHash, meta, project2, slug, queue) {
   if (metaEntry?.hash === localHash) return false;
   return true;
 }
-function planSlugsNeedingAutosave(deps, project2, slugs) {
+function resolveAutosaveProject(meta, queue, defaultProject, slug) {
+  const candidates = /* @__PURE__ */ new Set();
+  const suffix = `/${slug}`;
+  for (const key of Object.keys(meta)) {
+    if (key.endsWith(suffix)) candidates.add(key.slice(0, -suffix.length));
+  }
+  for (const entry of queue) {
+    if (entry.slug === slug) candidates.add(entry.project);
+  }
+  if (candidates.size === 1) return [...candidates][0];
+  return defaultProject;
+}
+function plansNeedingAutosave(deps, project2, slugs) {
   const meta = parseMeta(deps.readMetaRaw());
   const queue = parseQueue(deps.readQueueRaw());
   const out = [];
   for (const slug of slugs) {
     const raw = deps.readLocal(slug);
     if (raw == null) continue;
+    const autosaveProject = resolveAutosaveProject(meta, queue, project2, slug);
     const hash = hashContent(normalizeEol(raw));
-    if (planDirtyForAutosave(hash, meta, project2, slug, queue)) out.push(slug);
+    if (planDirtyForAutosave(hash, meta, autosaveProject, slug, queue)) out.push({ project: autosaveProject, slug });
   }
   return out;
 }
@@ -8555,11 +8600,11 @@ async function planAutoEnqueueDirty(deps, opts = {}) {
     }
   }
   const enqueued = [];
-  for (const slug of planSlugsNeedingAutosave(deps, project2, slugs)) {
-    const raw = deps.readLocal(slug);
+  for (const entry of plansNeedingAutosave(deps, project2, slugs)) {
+    const raw = deps.readLocal(entry.slug);
     if (raw == null) continue;
-    enqueuePlanPush(deps, { project: project2, slug, hash: hashContent(normalizeEol(raw)) }, { detach: false });
-    enqueued.push(slug);
+    enqueuePlanPush(deps, { project: entry.project, slug: entry.slug, hash: hashContent(normalizeEol(raw)) }, { detach: false });
+    enqueued.push(entry.slug);
   }
   if (enqueued.length) deps.detachSync();
   return enqueued;
@@ -11210,6 +11255,11 @@ function defaultWorktreePath(repoRoot, branch) {
   const safe = branch.replace(/[/\\]+/g, "-");
   return (0, import_node_path15.join)((0, import_node_path15.dirname)(repoRoot), "mmi-worktrees", safe);
 }
+function resolveWorktreeBase(from, remote) {
+  const remotePrefix = `${remote}/`;
+  const fetchBranch = from.startsWith(remotePrefix) ? from.slice(remotePrefix.length) : void 0;
+  return { base: from, fetchBranch };
+}
 
 // src/northstar-context.ts
 var SESSION_START_NORTHSTAR_TIMEOUT_MS = 3e3;
@@ -13621,35 +13671,18 @@ async function detectPublicIp(fetchImpl = fetch) {
   if (!validStageLiveIp(ip)) throw new Error(`public IP detection returned a non-IP body from ${IP_ECHO_URL}: "${ip.slice(0, 80)}"`);
   return ip;
 }
-function ghDispatchArgs(workflow, inputs) {
-  const args = ["workflow", "run", workflow, "--repo", STAGE_LIVE_HUB_REPO];
-  for (const [key, value] of Object.entries(inputs)) args.push("-f", `${key}=${value}`);
-  return args;
-}
 function stageLiveUpSteps(t) {
   return [
     { label: `detect your public IP (${IP_ECHO_URL}, bounded)` },
-    {
-      label: `deploy ${t.ref ?? "<current branch>"} to the ${t.slug} dev stage via the central deployer`,
-      command: `gh ${ghDispatchArgs("tenant-deploy.yml", { slug: t.slug, repo: t.repo, ref: t.ref ?? "<branch>", stage: "dev" }).join(" ")}`
-    },
-    {
-      label: `gate ${t.host} to your IP at the Cloudflare edge (ephemeral firewall_custom skip rule)`,
-      command: `gh ${ghDispatchArgs("tenant-control.yml", { slug: t.slug, stage: "dev", action: "cf-gate-allow", host: t.host, ip: "<your ip>" }).join(" ")}`
-    },
+    { label: `deploy ${t.ref ?? "<current branch>"} to the ${t.slug} dev stage via the Hub backend (tenant-deploy)` },
+    { label: `gate ${t.host} to your IP at the Cloudflare edge via the Hub backend (tenant-control cf-gate-allow)` },
     { label: "tear down when done", command: "mmi-cli stage --live --down --apply" }
   ];
 }
 function stageLiveDownSteps(t) {
   return [
-    {
-      label: `stop the ${t.slug} dev runtime`,
-      command: `gh ${ghDispatchArgs("tenant-control.yml", { slug: t.slug, stage: "dev", action: "stop" }).join(" ")}`
-    },
-    {
-      label: "remove the Cloudflare edge gate (the stage goes dark even if restarted)",
-      command: `gh ${ghDispatchArgs("tenant-control.yml", { slug: t.slug, stage: "dev", action: "cf-gate-clear", host: t.host }).join(" ")}`
-    }
+    { label: `stop the ${t.slug} dev runtime via the Hub backend (tenant-control stop)` },
+    { label: `remove the Cloudflare edge gate for ${t.host} via the Hub backend (tenant-control cf-gate-clear)` }
   ];
 }
 async function runStageLiveUp(deps, t) {
@@ -13657,8 +13690,8 @@ async function runStageLiveUp(deps, t) {
   const ip = (await deps.detectIp()).trim();
   if (!validStageLiveIp(ip)) throw new Error(`stage --live: detected public IP is not a literal IPv4/IPv6 address: "${ip.slice(0, 80)}"`);
   if (!t.host?.trim()) throw new Error("stage --live: cannot resolve the dev edge host (registry edgeDomains.dev)");
-  await deps.run("gh", ghDispatchArgs("tenant-deploy.yml", { slug: t.slug, repo: t.repo, ref: t.ref, stage: "dev" }));
-  await deps.run("gh", ghDispatchArgs("tenant-control.yml", { slug: t.slug, stage: "dev", action: "cf-gate-allow", host: t.host, ip }));
+  await deps.deployDev({ repo: t.repo, ref: t.ref });
+  await deps.control({ repo: t.repo, action: "cf-gate-allow", host: t.host, ip });
   return {
     command: "stage --live",
     mode: "up",
@@ -13672,8 +13705,8 @@ async function runStageLiveUp(deps, t) {
 }
 async function runStageLiveDown(deps, t) {
   if (!t.host?.trim()) throw new Error("stage --live: cannot resolve the dev edge host (registry edgeDomains.dev)");
-  await deps.run("gh", ghDispatchArgs("tenant-control.yml", { slug: t.slug, stage: "dev", action: "stop" }));
-  await deps.run("gh", ghDispatchArgs("tenant-control.yml", { slug: t.slug, stage: "dev", action: "cf-gate-clear", host: t.host }));
+  await deps.control({ repo: t.repo, action: "stop" });
+  await deps.control({ repo: t.repo, action: "cf-gate-clear", host: t.host });
   return {
     command: "stage --live",
     mode: "down",
@@ -14400,12 +14433,13 @@ async function runHotfixRelease(deps, versionInput, options = {}) {
       "report",
       meta.publishDir
     );
-    const publish = deploy.deployStatus === "failure" ? null : await dispatchPublishIfRequired(deps, ctx, meta, deployModel, "main", tag, true, "report");
+    const publish = deploy.deployStatus === "success" ? await dispatchPublishIfRequired(deps, ctx, meta, deployModel, "main", tag, true, "report") : null;
     let dispatch = appendPublishDispatch(deploy, publish);
-    if (!publish && deploy.deployStatus === "failure" && meta.publishRequired && (deployModel === "tenant-container" || deployModel === "solo-container")) {
+    if (!publish && deploy.deployStatus !== "success" && meta.publishRequired && (deployModel === "tenant-container" || deployModel === "solo-container")) {
+      const reason = deploy.deployStatus === "failure" ? "box deploy failed \u2014 redeploy the box before publishing" : "box deploy not confirmed (run with --watch) \u2014 publish after the box deploy lands";
       dispatch = {
         ...dispatch,
-        note: `${dispatch.note}; tenant-publish.yml skipped (box deploy failed \u2014 redeploy the box before publishing)`
+        note: `${dispatch.note}; tenant-publish.yml skipped (${reason})`
       };
     }
     deployNote = dispatch.note;
@@ -17598,6 +17632,23 @@ var import_promises7 = require("node:fs/promises");
 var import_node_path23 = require("node:path");
 var import_node_os5 = require("node:os");
 
+// src/plugin-guard.ts
+function buildPluginGuardDecision(i) {
+  if (!i.isOrgRepo) return { state: "not-org" };
+  if (!i.installRecordPresent) return { state: "no-install" };
+  if (!i.marketplaceClonePresent || !i.pluginCachePresent) return { state: "unresolved" };
+  return { state: "healthy" };
+}
+function buildGuardSessionStartLine(state, opts = {}) {
+  if (state === "healthy" || state === "not-org") return { exitCode: 0 };
+  const recovery = opts.recovery ?? "mmi-cli plugin-heal";
+  const reason = state === "no-install" ? "MMI plugin is not installed for this user/session" : "MMI plugin is installed but its marketplace/cache is unresolved";
+  return {
+    line: `[mmi-guard] ${reason}; run ${recovery} and restart Claude Code / reload plugins.`,
+    exitCode: 1
+  };
+}
+
 // src/cursor-plugin-seed.ts
 var import_node_child_process12 = require("node:child_process");
 var import_node_fs22 = require("node:fs");
@@ -17789,20 +17840,6 @@ function pluginInstallManualFix(projectPath, surface = "claude-cli") {
   const register = surface === "codex" ? `\`codex plugin add ${MMI_PLUGIN_ID}\`` : surface === "cursor" ? `import the MMI Team Marketplace in Cursor Dashboard \u2192 Settings \u2192 Plugins (or enable the MMI plugin from the marketplace panel)` : surface === "shell" ? `enable the MMI plugin in your client` : surface === "claude-vscode" ? `\`claude plugin enable ${MMI_PLUGIN_ID}\`` : `\`/plugin install ${MMI_PLUGIN_ID}\``;
   return `run ${register} then ${reloadAction(surface)} to register the install record for ${projectPath}`;
 }
-function isMmiPluginEnabled(settings) {
-  return Boolean(settings?.enabledPlugins?.[MMI_PLUGIN_ID]);
-}
-function buildSettingsPluginDriftCheck(input) {
-  const base = {
-    ok: true,
-    label: "org plugin wiring in .claude/settings.json (mmi@mutmutco)",
-    fix: "the Claude Code app pruned mmi@mutmutco from the tracked .claude/settings.json (it does this at session start when the mutmutco marketplace source does not resolve, #1805); restore it with `git checkout -- .claude/settings.json` before committing, or the whole org skill set is disabled for the branch"
-  };
-  const enabled = input.settings?.enabledPlugins;
-  if (!input.isOrgRepo || !enabled || Object.keys(enabled).length === 0) return base;
-  if (!enabled[MMI_PLUGIN_ID]) return { ...base, ok: false };
-  return base;
-}
 function hasProjectInstallRecord(file, pluginId, projectPath) {
   const records = file?.plugins?.[pluginId];
   if (!Array.isArray(records)) return false;
@@ -17825,7 +17862,7 @@ function buildPluginInstallRecordCheck(input) {
     fix: pluginInstallManualFix(input.projectPath, input.surface),
     pluginId
   };
-  if (!input.isOrgRepo || !isMmiPluginEnabled(input.settings)) return base;
+  if (!input.isOrgRepo) return base;
   if (hasAnyPluginRecords(input.installed, LEGACY_MMI_PLUGIN_ID) && !hasAnyPluginRecords(input.installed, pluginId)) {
     return {
       ...base,
@@ -18086,8 +18123,9 @@ function reloadAction(surface) {
       return "restart Claude Code (or run /reload-plugins)";
   }
 }
-var CLAUDE_RECOVERY = `claude plugin marketplace remove ${LEGACY_MMI_MARKETPLACE} && claude plugin marketplace remove mutmutco && claude plugin marketplace add mutmutco/MMI-Hub && claude plugin install mmi@mutmutco`;
+var CLAUDE_RECOVERY = `claude plugin marketplace remove ${LEGACY_MMI_MARKETPLACE} && claude plugin marketplace remove mutmutco && claude plugin marketplace add mutmutco/MMI-Hub --ref main && claude plugin install mmi@mutmutco`;
 var CODEX_RECOVERY = `codex plugin marketplace remove ${LEGACY_MMI_MARKETPLACE} && codex plugin marketplace remove mutmutco && codex plugin marketplace add mutmutco/MMI-Hub --ref main && codex plugin add mmi@mutmutco`;
+var CURSOR_RECOVERY = "in Cursor Dashboard \u2192 Settings \u2192 Plugins, click Update next to the MMI Team Marketplace";
 var OPENCODE_PLUGIN_PACKAGE = "@mutmutco/opencode-mmi";
 var OPENCODE_PLUGIN_SPEC = `${OPENCODE_PLUGIN_PACKAGE}@latest`;
 var OPENCODE_PLUGIN_INSTALL_COMMAND = `mmi-cli doctor --apply`;
@@ -18136,7 +18174,10 @@ var PLUGIN_SURFACE_HEAL = {
     healSteps: [
       { args: ["plugin", "marketplace", "remove", LEGACY_MMI_MARKETPLACE], gated: false },
       { args: ["plugin", "marketplace", "remove", "mutmutco"], gated: false },
-      { args: ["plugin", "marketplace", "add", "mutmutco/MMI-Hub"], gated: true },
+      // Pin --ref main: the marketplace clone must track `main` (the released branch the plugin pins in
+      // .claude-plugin/marketplace.json source.ref), removing the dev-vs-main skew that triggers the prune
+      // and doubles fetch exposure. Mirrors the existing codex entry (#2038).
+      { args: ["plugin", "marketplace", "add", "mutmutco/MMI-Hub", "--ref", "main"], gated: true },
       { args: ["plugin", "install", "mmi@mutmutco"], gated: true },
       { args: ["plugin", "enable", "mmi@mutmutco"], gated: false }
     ],
@@ -18159,10 +18200,10 @@ var PLUGIN_SURFACE_HEAL = {
   },
   cursor: {
     delivery: "cursor-cache",
-    recovery: "in Cursor Dashboard \u2192 Settings \u2192 Plugins, click Update next to the MMI Team Marketplace",
+    recovery: CURSOR_RECOVERY,
     healSteps: null,
-    fix: (surface) => `in Cursor Dashboard \u2192 Settings \u2192 Plugins, click Update next to the MMI Team Marketplace; then ${reloadAction(surface)} to reload MMI skills + hooks`,
-    updateRecipe: []
+    fix: (surface) => `${CURSOR_RECOVERY}; then ${reloadAction(surface)} to reload MMI skills + hooks`,
+    updateRecipe: [CURSOR_RECOVERY]
   },
   opencode: {
     delivery: "npm",
@@ -18203,9 +18244,21 @@ function surfaceToken(surface) {
 var PLUGIN_UPDATE_RECIPES = {
   claude: PLUGIN_SURFACE_HEAL.claude.updateRecipe,
   codex: PLUGIN_SURFACE_HEAL.codex.updateRecipe,
+  cursor: PLUGIN_SURFACE_HEAL.cursor.updateRecipe,
   opencode: PLUGIN_SURFACE_HEAL.opencode.updateRecipe,
   cli: ["npm install -g @mutmutco/cli@latest"]
 };
+var PLUGIN_GUIDE_SURFACES = [
+  { key: "cli", label: "npm CLI", versionKeys: ["cli"] },
+  { key: "claude", label: "Claude Code", versionKeys: ["claudePlugin"] },
+  { key: "codex", label: "Codex", versionKeys: ["codexMarketplace", "codexActiveCache"] },
+  { key: "cursor", label: "Cursor", versionKeys: [] },
+  { key: "opencode", label: "OpenCode", versionKeys: ["opencodePlugin"] }
+];
+function renderSurfaceGuide(label, steps) {
+  if (!steps.length) return [];
+  return [`  ${label}`, ...steps.map((step) => `    ${step}`)];
+}
 function highestSemver(versions) {
   return versions.reduce((best, v) => {
     if (!isSemverVersion2(v)) return best;
@@ -18233,20 +18286,24 @@ function buildPluginUpdateReport(input) {
 function renderPluginUpdateReport(report) {
   const v = report.versions;
   const show = (x) => x ?? "unknown";
-  return [
-    "MMI versions:",
-    `  CLI:                  ${show(v.cli)}`,
-    `  Claude plugin:        ${show(v.claudePlugin)}`,
-    `  Codex marketplace:    ${show(v.codexMarketplace)}`,
-    `  Codex active cache:   ${show(v.codexActiveCache)}`,
-    `  OpenCode plugin:      ${show(v.opencodePlugin)}`,
-    `  latest release:       ${show(v.released)}`,
-    "Update recipes (per surface):",
-    `  Claude:   ${report.recipes.claude.join(" ; ")}`,
-    `  Codex:    ${report.recipes.codex.join(" ; ")}`,
-    `  OpenCode: ${report.recipes.opencode.join(" ; ")}`,
-    `  npm CLI:  ${report.recipes.cli.join(" ; ")}`
+  const versionRows = [
+    ["mmi-cli", show(v.cli)],
+    ["Claude plugin", show(v.claudePlugin)],
+    ["Codex marketplace", show(v.codexMarketplace)],
+    ["Codex active cache", show(v.codexActiveCache)],
+    ["OpenCode plugin", show(v.opencodePlugin)]
+  ];
+  const pad = Math.max(...versionRows.map(([label]) => label.length));
+  const lines = [
+    `MMI versions  (target release: ${show(v.released)})`,
+    ...versionRows.map(([label, value]) => `  ${label.padEnd(pad)}  ${value}`),
+    "",
+    "Update commands by surface"
   ];
+  for (const surface of PLUGIN_GUIDE_SURFACES) {
+    lines.push(...renderSurfaceGuide(surface.label, report.recipes[surface.key]));
+  }
+  return lines;
 }
 function buildDoctorJsonPayload(input) {
   return {
@@ -18757,18 +18814,21 @@ function renderPluginUpdateReportStaleOnly(report) {
   const released = v.released;
   if (!released) return [];
   const isStale = (current) => Boolean(current && isSemverVersion2(current) && compareVersions(current, released) < 0);
-  const recipeLines = [];
-  if (isStale(v.cli)) recipeLines.push(`  npm CLI:  ${report.recipes.cli.join(" ; ")}`);
-  if (isStale(v.claudePlugin)) recipeLines.push(`  Claude:   ${report.recipes.claude.join(" ; ")}`);
-  if (isStale(v.codexMarketplace) || isStale(v.codexActiveCache)) {
-    recipeLines.push(`  Codex:    ${report.recipes.codex.join(" ; ")}`);
+  const blocks = [];
+  for (const surface of PLUGIN_GUIDE_SURFACES) {
+    if (!surface.versionKeys.some((k) => isStale(v[k]))) continue;
+    blocks.push(...renderSurfaceGuide(surface.label, report.recipes[surface.key]));
   }
-  if (isStale(v.opencodePlugin)) recipeLines.push(`  OpenCode: ${report.recipes.opencode.join(" ; ")}`);
-  if (!recipeLines.length) return [];
-  return ["Update recipes (stale surfaces):", ...recipeLines];
+  if (!blocks.length) return [];
+  return ["Update commands (stale surfaces):", ...blocks];
 }
+var DOCTOR_VERBOSE_HINT = "Run mmi-cli doctor --verbose for the full audit checklist + version report.";
 function renderTerseDoctorReport(input) {
-  if (!input.gaps.length) return [];
+  const cliVersion = input.updateReport.versions.cli;
+  const versionSuffix = cliVersion ? ` (mmi-cli ${cliVersion})` : "";
+  if (!input.gaps.length) {
+    return [`\u2713 MMI doctor: all checks passed${versionSuffix}.`, DOCTOR_VERBOSE_HINT];
+  }
   const lines = [];
   for (const c of input.gaps) {
     lines.push(`\u2717 ${c.label}`);
@@ -18779,8 +18839,39 @@ function renderTerseDoctorReport(input) {
     lines.push("");
     lines.push(...stale);
   }
+  lines.push("");
+  lines.push(`\u26A0 ${input.gaps.length} item(s) need attention \u2014 ${DOCTOR_VERBOSE_HINT}`);
   return lines;
 }
+var PLUGIN_RESOLVABILITY_LABEL = "MMI plugin resolvability (marketplace + cache present)";
+function buildPluginResolvabilityCheck(input) {
+  const { state } = buildPluginGuardDecision(input);
+  const surface = input.surface ?? "shell";
+  switch (state) {
+    case "not-org":
+      return { ok: true, label: PLUGIN_RESOLVABILITY_LABEL, fix: "", state };
+    case "healthy":
+      return { ok: true, label: PLUGIN_RESOLVABILITY_LABEL, fix: "", state };
+    case "no-install":
+      return {
+        ok: false,
+        label: PLUGIN_RESOLVABILITY_LABEL,
+        fix: `run: ${PLUGIN_SURFACE_HEAL[surfaceToken(surface) ?? "claude"]?.recovery ?? PLUGIN_SURFACE_HEAL.claude.recovery}`,
+        state
+      };
+    case "unresolved":
+      return {
+        ok: false,
+        label: PLUGIN_RESOLVABILITY_LABEL,
+        fix: "run: mmi-cli plugin-heal",
+        state
+      };
+    default: {
+      const _exhaustive = state;
+      return _exhaustive;
+    }
+  }
+}
 
 // src/kb-drift-report.ts
 var import_node_fs23 = require("node:fs");
@@ -19151,13 +19242,23 @@ var installedPluginsPath = (surface = detectSurface(process.env)) => {
   const homeDir = surface === "codex" ? ".codex" : ".claude";
   return (0, import_node_path23.join)((0, import_node_os5.homedir)(), homeDir, "plugins", "installed_plugins.json");
 };
-function readInstalledPlugins() {
+function readInstalledPlugins(surface = detectSurface(process.env)) {
   try {
-    return JSON.parse((0, import_node_fs26.readFileSync)(installedPluginsPath(), "utf8"));
+    return JSON.parse((0, import_node_fs26.readFileSync)(installedPluginsPath(surface), "utf8"));
   } catch {
     return null;
   }
 }
+function snapshotPluginGuardInput(surface = detectSurface(process.env), isOrgRepo = false) {
+  const homeDir = surface === "codex" ? ".codex" : ".claude";
+  const installed = readInstalledPlugins(surface);
+  return {
+    isOrgRepo,
+    installRecordPresent: hasUserInstallRecord(installed, MMI_PLUGIN_ID) || hasProjectInstallRecord(installed, MMI_PLUGIN_ID, process.cwd()),
+    marketplaceClonePresent: (0, import_node_fs26.existsSync)((0, import_node_path23.join)((0, import_node_os5.homedir)(), homeDir, "plugins", "marketplaces", "mutmutco")),
+    pluginCachePresent: (0, import_node_fs26.existsSync)((0, import_node_path23.join)((0, import_node_os5.homedir)(), homeDir, "plugins", "cache", "mutmutco", "mmi"))
+  };
+}
 function installedPluginSources() {
   return ["claude", "codex"].map((surface) => {
     const recordPath = (0, import_node_path23.join)((0, import_node_os5.homedir)(), `.${surface}`, "plugins", "installed_plugins.json");
@@ -19734,7 +19835,6 @@ async function runDoctor(opts, io = consoleIo) {
     }
   }
   checks.push(pluginCheck);
-  checks.push(buildSettingsPluginDriftCheck({ isOrgRepo: Boolean(cfg.sagaApiUrl), settings: claudeSettings }));
   let legacyPluginCheck = buildLegacyPluginInstallCheck({
     isOrgRepo: Boolean(cfg.sagaApiUrl),
     sources: installedPluginSources(),
@@ -19791,6 +19891,18 @@ async function runDoctor(opts, io = consoleIo) {
     }
   }
   checks.push(driftCheck);
+  checks.push(
+    buildPluginResolvabilityCheck({
+      ...snapshotPluginGuardInput(surface, Boolean(cfg.sagaApiUrl)),
+      surface
+    })
+  );
+  if (repairFull && Boolean(cfg.sagaApiUrl) && (surfaceToken(surface) === "claude" || surfaceToken(surface) === "codex")) {
+    const guardResult = ensureUserScopeGuardHook();
+    if (guardResult === "written") {
+      io.err(`  \u21BB installed user-scope MMI guard hook (${surface === "codex" ? "~/.codex" : "~/.claude"}/settings.json) \u2014 survives a plugin prune`);
+    }
+  }
   let installedVersionCheck = buildInstalledPluginVersionCheck({
     isOrgRepo: Boolean(cfg.sagaApiUrl),
     sources: installedPluginSources(),
@@ -20175,6 +20287,79 @@ async function runDoctor(opts, io = consoleIo) {
   io.log(gaps.length ? `
 ${gaps.length} item(s) need attention.` : "\nAll set \u2014 you are ready.");
 }
+var USER_SCOPE_GUARD_MARKER = "mmi-guard:v1";
+var USER_SCOPE_GUARD_COMMAND = `mmi-cli guard --session-start || true # ${USER_SCOPE_GUARD_MARKER}`;
+function settingsHasGuardHook(settings) {
+  const groups = settings?.hooks?.SessionStart;
+  if (!Array.isArray(groups)) return false;
+  return groups.some(
+    (g) => Array.isArray(g?.hooks) && g.hooks.some((h) => typeof h?.command === "string" && h.command.includes(USER_SCOPE_GUARD_MARKER))
+  );
+}
+function mergeGuardHook(settings) {
+  const next = settings && typeof settings === "object" ? { ...settings } : {};
+  if (settingsHasGuardHook(next)) return next;
+  const hooks = { ...next.hooks ?? {} };
+  const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+  sessionStart.push({ hooks: [{ type: "command", command: USER_SCOPE_GUARD_COMMAND, timeout: 10 }] });
+  hooks.SessionStart = sessionStart;
+  next.hooks = hooks;
+  return next;
+}
+var userScopeSettingsPath = (surface = detectSurface(process.env)) => (0, import_node_path23.join)((0, import_node_os5.homedir)(), surface === "codex" ? ".codex" : ".claude", "settings.json");
+function ensureUserScopeGuardHook(opts = {}) {
+  const path2 = opts.settingsPath ?? userScopeSettingsPath();
+  try {
+    let current = null;
+    if ((0, import_node_fs26.existsSync)(path2)) {
+      try {
+        current = JSON.parse((0, import_node_fs26.readFileSync)(path2, "utf8"));
+      } catch {
+        return "failed";
+      }
+    }
+    if (settingsHasGuardHook(current)) return "already";
+    const merged = mergeGuardHook(current);
+    (0, import_node_fs26.mkdirSync)((0, import_node_path23.dirname)(path2), { recursive: true });
+    if ((0, import_node_fs26.existsSync)(path2)) (0, import_node_fs26.copyFileSync)(path2, `${path2}.bak`);
+    (0, import_node_fs26.writeFileSync)(path2, `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+    return "written";
+  } catch {
+    return "failed";
+  }
+}
+async function runGuard(opts = {}) {
+  void opts;
+  try {
+    const surface = detectSurface(process.env);
+    const cfg = await loadConfig();
+    const input = snapshotPluginGuardInput(surface, Boolean(cfg.sagaApiUrl));
+    const { state } = buildPluginGuardDecision(input);
+    const { line, exitCode } = buildGuardSessionStartLine(state);
+    if (line) console.error(line);
+    process.exitCode = exitCode;
+  } catch {
+    process.exitCode = 0;
+  }
+}
+async function runPluginHeal(surface = detectSurface(process.env)) {
+  const token = surface === "codex" ? "codex" : "claude";
+  const tableKey = surfaceToken(surface) ?? "claude";
+  const descriptor = PLUGIN_SURFACE_HEAL[tableKey];
+  if (!descriptor.healSteps) {
+    console.log(descriptor.recovery);
+    console.log(`Then: ${reloadAction(surface)}`);
+    return;
+  }
+  const healed = await applyPluginHeal(token, surface, console.log, { force: true });
+  if (healed) {
+    console.log(`  \u2713 MMI plugin reinstalled \u2014 ${reloadAction(surface)} to load MMI commands`);
+  } else {
+    console.log(`  \u2717 Auto-heal failed or was skipped. Run manually:
+  ${descriptor.recovery}`);
+  }
+}
 
 // src/index.ts
 var GC_GH_TIMEOUT_MS2 = 2e4;
@@ -20637,18 +20822,21 @@ function acquireWorktreeSetupLock(worktreeRoot) {
   }
 }
 var worktree = program2.command("worktree").description("self-provisioning worktrees \u2014 install deps + copy local-only config");
-worktree.command("create <branch>").description("create a worktree from a base ref and provision it (install deps + copy local-only config)").option("--from <ref>", "base ref to branch from", "origin/development").option("--path <path>", "worktree path (default: ../mmi-worktrees/<branch>)").option("--remote <name>", "remote to fetch the base from", "origin").option("--json", "machine-readable output").action(async (branch, o) => {
+worktree.command("create <branch>").description("create a worktree from a base ref and provision it (install deps + copy local-only config)").option("--from <ref>", "base ref to branch from", "origin/development").option("--path <path>", "worktree path (default: ../mmi-worktrees/<branch>)").option("--remote <name>", "remote to fetch when --from is a <remote>/<branch> ref", "origin").option("--json", "machine-readable output").action(async (branch, o) => {
   try {
     const repoRoot = (await execFileP2("git", ["rev-parse", "--show-toplevel"], { timeout: GIT_TIMEOUT_MS }).catch(() => ({ stdout: "" }))).stdout.trim() || process.cwd();
     const wtPath = o.path ?? defaultWorktreePath(repoRoot, branch);
-    const baseBranch = o.from.startsWith(`${o.remote}/`) ? o.from.slice(o.remote.length + 1) : void 0;
-    if (baseBranch) await execFileP2("git", ["fetch", o.remote, baseBranch], { timeout: GH_MUTATION_TIMEOUT_MS }).catch(() => void 0);
-    await execFileP2("git", ["worktree", "add", wtPath, "-b", branch, o.from], { timeout: GH_MUTATION_TIMEOUT_MS });
+    const { base, fetchBranch } = resolveWorktreeBase(o.from, o.remote);
+    if (fetchBranch) {
+      const fetchErr = await execFileP2("git", ["fetch", o.remote, fetchBranch], { timeout: GH_MUTATION_TIMEOUT_MS }).then(() => void 0).catch((e) => (e instanceof Error ? e.message : String(e)).split("\n")[0]);
+      if (fetchErr) console.error(`  warning: could not fetch ${o.remote}/${fetchBranch} (${fetchErr}); base ${base} may be stale`);
+    }
+    await execFileP2("git", ["worktree", "add", wtPath, "-b", branch, base], { timeout: GH_MUTATION_TIMEOUT_MS });
     const report = await provisionWorktree(wtPath, makeProvisionDeps(wtPath, Boolean(o.json), (m) => {
       if (!o.json) console.error(`  ${m}`);
     }));
-    if (o.json) return console.log(JSON.stringify({ branch, path: wtPath, base: o.from, ...report }, null, 2));
-    console.log(`worktree ready: ${wtPath} (branch ${branch} from ${o.from})`);
+    if (o.json) return console.log(JSON.stringify({ branch, path: wtPath, base, ...report }, null, 2));
+    console.log(`worktree ready: ${wtPath} (branch ${branch} from ${base})`);
     console.log(`  installed: ${report.installed.map((i) => i.dir || ".").join(", ") || "none"}`);
     console.log(`  copied: ${report.copied.join(", ") || "none"}`);
   } catch (e) {
@@ -22261,9 +22449,17 @@ async function runStageLiveCommand(o) {
     if (o.json) return console.log(JSON.stringify({ command: "stage --live", mode, slug: target.slug, repo: target.repo, ref: o.down ? void 0 : target.ref, steps }, null, 2));
     return console.log(renderSteps(`mmi-cli stage --live${o.down ? " --down" : ""}: dry-run plan`, steps));
   }
+  const rcDeps = registryClientDeps(await loadConfig());
   const deps = {
     detectIp: () => detectPublicIp(),
-    run: async (file, args) => (await execFileP2(file, args, { timeout: GH_MUTATION_TIMEOUT_MS })).stdout
+    deployDev: async ({ repo, ref }) => {
+      const res = await tenantDeploy({ repo, stage: "dev", ref }, rcDeps);
+      if (!res.ok) throw new Error(`dev deploy dispatch failed: ${res.body?.error ?? res.error ?? `HTTP ${res.status}`}`);
+    },
+    control: async ({ repo, action, host, ip }) => {
+      const res = await tenantControl({ repo, stage: "dev", action, host, ip }, rcDeps);
+      if (!res.ok) throw new Error(`tenant control ${action} dispatch failed: ${res.body?.error ?? res.error ?? `HTTP ${res.status}`}`);
+    }
   };
   try {
     const result = o.down ? await runStageLiveDown(deps, target) : await runStageLiveUp(deps, target);
@@ -23012,6 +23208,8 @@ program2.command("doctor").description("check onboarding gates and auto-heal CLI
   // Commander maps `--no-repo-writes` to `repoWrites: false`; translate to the explicit `noRepoWrites` flag.
   runDoctor({ ...opts, noRepoWrites: opts.repoWrites === false })
 ));
+program2.command("guard").description("detect a pruned/unresolved MMI plugin on disk; loud one-line stderr at session start").option("--session-start", "run in user-scope SessionStart mode").action((opts) => runGuard({ sessionStart: opts.sessionStart }));
+program2.command("plugin-heal").description("reinstall + re-enable the MMI plugin (recover from a marketplace prune)").action(() => runPluginHeal());
 program2.command("session-start").description("run the SessionStart verbs (rules sync, saga session+show, saga health, whoami, doctor, plan-store check) in one process; docs sync runs detached").action(async () => {
   if (isInsideRepoSubdir(process.cwd())) {
     console.error("[mmi-hook] session-start: cwd is a repository SUBDIRECTORY \u2014 skipping the SessionStart hook (spine/docs/plan/saga delivery); run it from the repo root.");

package/dist/saga.cjs

@@ -3522,18 +3522,23 @@ function headPrompt(state) {
   const decisions = shownDecisions(state.decisions);
   const actions = (state.actionLog ?? []).slice(-HEAD_PROMPT_ACTION_LIMIT);
   return [
-    "You maintain ONE durable slot of a work-session: PINNED (things worth remembering). Given the CURRENT",
-    "HEAD and the recent TRANSCRIPT + DECISIONS, return an updated PINNED only. Keep it tight and concrete;",
-    "keep anything the user pinned; never invent; preserve Turkish characters (\xE7 \u011F \u0131 \u0130 \xF6 \u015F \xFC) exactly. Do",
-    "NOT manage next or the checklist \u2014 the note path owns those. The ANCHOR is the read-only North-Star \u2014",
-    "NEVER change it. Never restate an unverified artifact-claim (a named file, PR, flag, or board state)",
-    "as settled fact \u2014 keep it as the belief it was recorded as.",
+    "You maintain two durable slots of a work-session: PINNED (things worth remembering) and a NEXT",
+    "SUGGESTION (a best-effort one-line hint for the next useful step). Given the CURRENT HEAD and the",
+    "recent TRANSCRIPT + DECISIONS, return an updated PINNED and, optionally, a next suggestion. Keep",
+    "PINNED tight and concrete; keep anything the user pinned; never invent; preserve Turkish characters",
+    "(\xE7 \u011F \u0131 \u0130 \xF6 \u015F \xFC) exactly. Do NOT manage the checklist \u2014 the note path owns that. The ANCHOR is the",
+    "read-only North-Star \u2014 NEVER change it. Never restate an unverified artifact-claim (a named file,",
+    "PR, flag, or board state) as settled fact \u2014 keep it as the belief it was recorded as.",
     "You MAY also propose supersessions: each DECISION is shown with its original stable 0-based index. Propose a",
     "supersession ONLY for a NEWER decision that directly contradicts/replaces an OLDER one where neither",
     "already carries a supersededBy. HIGH PRECISION \u2014 propose ONLY when you are confident the older claim",
     "is now false or obsolete; the newer decision's timestamp MUST be later than the older's (newer-supersedes-",
-    "older only, never the reverse). When unsure, propose nothing. NEVER touch the anchor, next, or checklist.",
-    'Output ONLY a JSON object: {"pinned":[string],"supersede":[{"older":int,"newer":int,"reason":string}]}.',
+    "older only, never the reverse). When unsure, propose nothing. NEVER touch the anchor or checklist.",
+    'For "next": propose a single concise actionable line (\u2264140 chars) describing the most useful next step',
+    "for a future session, derived from the transcript. This is a best-effort suggestion shown only when",
+    "the user has not set their own NEXT. Use an empty string if nothing concrete emerges \u2014 never invent.",
+    "Preserve Turkish characters exactly.",
+    'Output ONLY a JSON object: {"pinned":[string],"next":string,"supersede":[{"older":int,"newer":int,"reason":string}]}.',
     "",
     "CURRENT HEAD:",
     JSON.stringify(state.head ?? {}, null, 2),
@@ -3557,6 +3562,9 @@ function parseHeadUpdate(raw) {
   if (!obj || typeof obj !== "object") return null;
   const u = {};
   if (Array.isArray(obj.pinned)) u.pinned = obj.pinned.filter((x) => typeof x === "string");
+  if (typeof obj.next === "string" && obj.next.trim()) {
+    u.nextAuto = obj.next.trim().slice(0, 280);
+  }
   if (Array.isArray(obj.supersede)) {
     const supersede = obj.supersede.filter((e) => {
       if (!e || typeof e !== "object") return false;

package/package.json

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