@mutmutco/cli 4.1.1 → 4.1.3

package/dist/main.cjs

@@ -2306,7 +2306,8 @@ __export(index_exports, {
   positionalTargetForm: () => positionalTargetForm,
   registryClientDeps: () => registryClientDeps,
   repoSlug: () => repoSlug,
-  suggestCommandPath: () => suggestCommandPath
+  suggestCommandPath: () => suggestCommandPath,
+  unknownCommandCandidates: () => unknownCommandCandidates
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -12867,10 +12868,10 @@ var rollout_plan_default = {
     note: "The v4.0.0 stamp happens at cut time (D6e #4463); until then the candidate is the origin/development head artifacts (built cli/dist + npm pack), identity proven by dist content hash (D6a)."
   },
   baseline: {
-    version: "4.1.1",
-    tag: "v4.1.1",
-    commit: "df9ba86cbdba",
-    npm: "@mutmutco/cli@4.1.1"
+    version: "4.1.3",
+    tag: "v4.1.3",
+    commit: "3164484f3f37",
+    npm: "@mutmutco/cli@4.1.3"
   },
   exitCriterion: "fleet-n-of-n",
   hubOnlyShortcut: "forbidden",
@@ -12887,14 +12888,14 @@ var rollout_plan_default = {
           repo: "mutmutco/mmi-hub",
           role: "canary",
           schedule: "train",
-          v3Target: "v4.1.1"
+          v3Target: "v4.1.3"
         }
       ],
       rollbackTrigger: "Any red inside the post-contract soak window: `devops train gate` FAIL attributable to the v4 doors, Hub endpoint health probe failure, a pre-v4 client admitted instead of receiving actionable HTTP 426, or npm consumer install/doctor failure on the v4-only dist.",
       rollback: {
         independent: true,
-        mechanism: "npm dist-tag latest -> 4.1.1 and redeploy the Hub Lambda from tag v4.1.1 (df9ba86cbdba); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
-        v3Target: "v4.1.1 (@mutmutco/cli@4.1.1, tag commit df9ba86cbdba \u2014 last known-good release carrying the repo-index v4-only contract)"
+        mechanism: "npm dist-tag latest -> 4.1.3 and redeploy the Hub Lambda from tag v4.1.3 (3164484f3f37); installed clients repair via `mmi-cli doctor`. No other cohort is touched.",
+        v3Target: "v4.1.3 (@mutmutco/cli@4.1.3, tag commit 3164484f3f37 \u2014 last known-good release carrying the repo-index v4-only contract)"
       }
     },
     {
@@ -19388,8 +19389,10 @@ init_client_version();
 var BOARD_SNAPSHOT_TIMEOUT_MS = 25e3;
 function isSnapshotShape(body) {
   const b = body;
+  const rate = b?.github?.rateLimit;
+  const githubValid = b?.github === void 0 || b.github.credential === "app_installation" && Number.isFinite(rate?.limit) && Number.isFinite(rate?.remaining) && Number.isFinite(rate?.cost) && typeof rate?.resetAt === "string";
   return Boolean(
-    b && typeof b === "object" && typeof b.project?.id === "string" && typeof b.project?.title === "string" && typeof b.viewer === "string" && b.viewer.length > 0 && Array.isArray(b.nodes) && Array.isArray(b.writableRepos) && Array.isArray(b.unreadableRepos) && Array.isArray(b.pullRequests) && Array.isArray(b.warnings) && typeof b.partial === "boolean"
+    b && typeof b === "object" && typeof b.project?.id === "string" && typeof b.project?.title === "string" && typeof b.viewer === "string" && b.viewer.length > 0 && Array.isArray(b.nodes) && Array.isArray(b.writableRepos) && Array.isArray(b.unreadableRepos) && Array.isArray(b.pullRequests) && Array.isArray(b.warnings) && typeof b.partial === "boolean" && githubValid
   );
 }
 async function fetchHubBoardSnapshot(request, deps) {
@@ -20172,6 +20175,10 @@ function renderBoardItem(item) {
 }
 function renderBoardReport(report) {
   const lines = [`Board \xB7 ${report.project.title} \xB7 @${report.viewer}`, renderBoardSource()];
+  if (report.github) {
+    const { limit, remaining, cost, resetAt } = report.github.rateLimit;
+    lines.push(`github: app installation \xB7 GraphQL ${remaining}/${limit} remaining \xB7 cost ${cost} \xB7 resets ${resetAt}`);
+  }
   renderScope(lines, "PRIMARY", report.repo, report.primary, report.viewer);
   renderScope(lines, "SECONDARY", "Other repos on this project", report.secondary, report.viewer);
   if (report.warnings.length) {
@@ -20284,6 +20291,7 @@ async function readBoard(options, deps = {}) {
   let collected;
   let writable;
   let pullRequests;
+  let github;
   let snapshotFallback;
   const attempt = deps.snapshot ? await fetchHubBoardSnapshot(
     {
@@ -20328,6 +20336,7 @@ async function readBoard(options, deps = {}) {
       unknown: new Set(snapshot.unreadableRepos.map((entry) => entry.repo.toLowerCase()))
     };
     pullRequests = snapshot.pullRequests;
+    github = snapshot.github;
   } else {
     if (attempt?.state === "unavailable") snapshotFallback = attempt.reason;
     collected = await collectBoardItems(cfg, { repo: options.repo, allowPartial: options.allowPartial, activeOnly: true }, deps);
@@ -20348,7 +20357,8 @@ async function readBoard(options, deps = {}) {
     warnings: collected.warnings,
     partial: collected.partial,
     source: "live",
-    ...pullRequests ? { pullRequests } : {}
+    ...pullRequests ? { pullRequests } : {},
+    ...github ? { github } : {}
   };
   if (options.includeBundleDetails || options.includeAllBodies) {
     await attachBundleDetails(report, client, options.allowPartial ?? false, { all: options.includeAllBodies });
@@ -25322,6 +25332,7 @@ function repoIndexV4BucketDigests(repo, chunks, embeddings) {
 
 // src/repo-index-cloud-client.ts
 var RETRY_ATTEMPTS2 = 3;
+var REPO_INDEX_GC_TIMEOUT_MS = 12e4;
 async function repoIndexSourceHostHeaders() {
   const { detectSurface: detectSurface2 } = await Promise.resolve().then(() => (init_plugin_guard_io(), plugin_guard_io_exports));
   return { [SOURCE_HOST_HEADER]: detectSurface2(process.env) };
@@ -25727,10 +25738,22 @@ async function statusRepoIndexCloud(repo, deps) {
     return { ok: false, error: e.message, code: "network" };
   }
 }
+function normalizeGcV4Repos(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [repo, value] of Object.entries(raw)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const removed = Array.isArray(value.removed) ? value.removed.filter((k) => typeof k === "string") : [];
+    const kept = Number(value.kept);
+    out[repo] = { removed, kept: Number.isFinite(kept) ? kept : 0 };
+  }
+  return out;
+}
 async function gcRepoIndexCloud(deps) {
   if (!deps.baseUrl) return { ok: false, error: "Hub API URL not configured" };
   const token = await deps.token();
   if (!token) return { ok: false, error: "no Hub session token (run `gh auth login`)" };
+  const timeoutMs = deps.timeoutMs ?? REPO_INDEX_GC_TIMEOUT_MS;
   try {
     const res = await fetchWithRetry(
       deps.fetch ?? fetch,
@@ -25740,13 +25763,32 @@ async function gcRepoIndexCloud(deps) {
         headers: { ...clientVersionHeaders(), Authorization: `Bearer ${token}`, "content-type": "application/json" },
         body: "{}"
       },
-      { attempts: RETRY_ATTEMPTS2, timeoutMs: deps.timeoutMs ?? REGISTRY_FETCH_TIMEOUT_MS, sleep: deps.retrySleep }
+      // Single attempt: GC tombstones authorities and deletes S3 objects. A timed-out POST may still
+      // finish on Hub; retrying would re-issue a destructive sweep without an authoritative receipt.
+      { attempts: 1, timeoutMs, sleep: deps.retrySleep }
     );
     const body = await res.json().catch(() => ({}));
     if (!res.ok) return { ok: false, error: body.error ?? `gc HTTP ${res.status}` };
-    return { ok: true, removed: body.removed ?? [] };
+    const removed = Array.isArray(body.removed) ? body.removed.filter((repo) => typeof repo === "string") : [];
+    const kept = Number(body.kept);
+    return {
+      ok: true,
+      removed,
+      kept: Number.isFinite(kept) ? kept : 0,
+      v4: {
+        dryRun: body.v4?.dryRun === true,
+        repos: normalizeGcV4Repos(body.v4?.repos)
+      }
+    };
   } catch (e) {
-    return { ok: false, error: e.message };
+    const msg = e.message || String(e);
+    if (/abort|timeout/i.test(msg)) {
+      return {
+        ok: false,
+        error: `repo-index gc timed out after ${timeoutMs}ms \u2014 Hub may still have completed the destructive sweep; run \`mmi-cli oracle repo-index status --cloud --json\` and verify before retrying`
+      };
+    }
+    return { ok: false, error: msg };
   }
 }
 
@@ -25893,6 +25935,16 @@ function buildGraphEdges(cwd, repo, commit, rosterRepos2) {
 }
 
 // src/repo-index-sync.ts
+function execFileUtf8(file, args) {
+  return new Promise((resolve5, reject) => {
+    (0, import_node_child_process15.execFile)(file, args, { encoding: "utf8", windowsHide: true }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve5(String(stdout ?? ""));
+    });
+  });
+}
+var ESTATE_CLASSIFY_CONCURRENCY = 8;
+var ESTATE_HEALTHY_CLASSIFY_BUDGET_MS = 5 * 601e3;
 var COMMIT3 = /^[a-f0-9]{40}$/;
 var SHA256 = /^[a-f0-9]{64}$/;
 var UTC_MILLIS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
@@ -25928,17 +25980,28 @@ function checkoutExactCommit(repo, dest, token, commit) {
   const head = git3(["rev-parse", "HEAD"]).trim().toLowerCase();
   if (head !== commit) throw new Error(`checkout of ${repo} resolved ${head}, not the requested commit ${commit}`);
 }
-function remoteHead(repo, token) {
+async function remoteHead(repo, token) {
   const basic = Buffer.from(`x-access-token:${token}`, "utf8").toString("base64");
-  const output = (0, import_node_child_process15.execFileSync)(
+  const stdout = await execFileUtf8(
     "git",
-    ["-c", `http.extraHeader=Authorization: Basic ${basic}`, "ls-remote", "--exit-code", `https://github.com/${repo}.git`, "HEAD"],
-    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }
+    ["-c", `http.extraHeader=Authorization: Basic ${basic}`, "ls-remote", "--exit-code", `https://github.com/${repo}.git`, "HEAD"]
   );
-  const match = String(output).match(/^([a-f0-9]{40})\s+HEAD$/m);
+  const match = stdout.match(/^([a-f0-9]{40})\s+HEAD$/m);
   if (!match) throw new Error(`could not resolve remote HEAD for ${repo}`);
   return match[1];
 }
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
 function verifiedReadyBase(statusValue, repo) {
   if (!statusValue || typeof statusValue !== "object" || Array.isArray(statusValue)) return null;
   const status = statusValue;
@@ -25946,8 +26009,9 @@ function verifiedReadyBase(statusValue, repo) {
   if (!v4 || typeof v4 !== "object" || Array.isArray(v4)) return null;
   const pointer = v4;
   const artifactDigests = pointer.artifactDigests;
+  const expectedArtifactDigests = pointer.materialLayout === 2 ? 1 : pointer.materialLayout === void 0 || pointer.materialLayout === 1 ? 2 : 0;
   const counts = [pointer.chunkCount, pointer.embeddingCount, pointer.tombstoneCount];
-  const structurallyVerified = status.repo === repo && pointer.repo === repo && pointer.state === "ready" && pointer.integrity === "verified" && typeof pointer.commit === "string" && COMMIT3.test(pointer.commit) && typeof pointer.digest === "string" && SHA256.test(pointer.digest) && Array.isArray(artifactDigests) && artifactDigests.length === 2 && new Set(artifactDigests).size === artifactDigests.length && artifactDigests.every((digest) => typeof digest === "string" && SHA256.test(digest)) && counts.every((count) => Number.isInteger(count) && Number(count) >= 0) && pointer.embeddingCount === pointer.chunkCount && typeof pointer.activatedAt === "string" && UTC_MILLIS.test(pointer.activatedAt) && Number.isFinite(Date.parse(pointer.activatedAt)) && new Date(pointer.activatedAt).toISOString() === pointer.activatedAt;
+  const structurallyVerified = status.repo === repo && pointer.repo === repo && pointer.state === "ready" && pointer.integrity === "verified" && typeof pointer.commit === "string" && COMMIT3.test(pointer.commit) && typeof pointer.digest === "string" && SHA256.test(pointer.digest) && Array.isArray(artifactDigests) && artifactDigests.length === expectedArtifactDigests && new Set(artifactDigests).size === artifactDigests.length && artifactDigests.every((digest) => typeof digest === "string" && SHA256.test(digest)) && counts.every((count) => Number.isInteger(count) && Number(count) >= 0) && pointer.embeddingCount === pointer.chunkCount && typeof pointer.activatedAt === "string" && UTC_MILLIS.test(pointer.activatedAt) && Number.isFinite(Date.parse(pointer.activatedAt)) && new Date(pointer.activatedAt).toISOString() === pointer.activatedAt;
   return structurallyVerified && typeof pointer.commit === "string" && typeof pointer.digest === "string" ? { commit: pointer.commit, digest: pointer.digest } : null;
 }
 function activePointerDigest(statusValue) {
@@ -26039,11 +26103,18 @@ async function syncEstateRepoIndex(opts) {
   const busy = new Set(
     (opts.skipRepos ?? []).map((repo) => normalizeRepoIndexRepo(repo)).filter((repo) => repo !== null)
   );
-  for (const repo of repos) {
+  const emit = (progress) => {
+    try {
+      opts.onClassify?.(progress);
+    } catch {
+    }
+  };
+  const classified = await mapLimit(repos, ESTATE_CLASSIFY_CONCURRENCY, async (repo) => {
     if (busy.has(repo)) {
-      drift.push({ repo, reason: "busy-elsewhere", action: "skip" });
-      skipped.push(`${repo}: a per-repo reconcile run is already publishing it`);
-      continue;
+      const row2 = { repo, reason: "busy-elsewhere", action: "skip" };
+      const warning = `${repo}: a per-repo reconcile run is already publishing it`;
+      emit({ row: row2, warning });
+      return { repo, row: row2, warning, base: null, expectedActiveDigest: void 0 };
     }
     let base = null;
     let expectedActiveDigest;
@@ -26066,7 +26137,7 @@ async function syncEstateRepoIndex(opts) {
     if (base && !forceFull) {
       if (!targetCommit) {
         try {
-          targetCommit = remoteHead(repo, opts.githubToken);
+          targetCommit = await remoteHead(repo, opts.githubToken);
         } catch {
           targetCommit = void 0;
         }
@@ -26075,25 +26146,43 @@ async function syncEstateRepoIndex(opts) {
         (error) => ({ ok: false, error: error.message })
       );
       if (provenance.ok && !provenance.deltaCompatible) {
-        drift.push({ repo, reason: "incompatible-provenance", action: "needs-full-rebuild", activeCommit: base.commit, ...targetCommit ? { targetCommit } : {} });
-        needsFullRebuild.push(repo);
-        skipped.push(`${repo}: DRIFT incompatible index provenance \u2014 the active authority at ${base.commit} was not built by ${CURRENT_REPO_INDEX_PROVENANCE_TOKEN}; migrate it explicitly with \`oracle repo-index sync-estate --repo ${repo} --full-rebuild ${CURRENT_REPO_INDEX_PROVENANCE_TOKEN}\``);
-        continue;
+        const row2 = {
+          repo,
+          reason: "incompatible-provenance",
+          action: "needs-full-rebuild",
+          activeCommit: base.commit,
+          ...targetCommit ? { targetCommit } : {}
+        };
+        const warning = `${repo}: DRIFT incompatible index provenance \u2014 the active authority at ${base.commit} was not built by ${CURRENT_REPO_INDEX_PROVENANCE_TOKEN}; migrate it explicitly with \`oracle repo-index sync-estate --repo ${repo} --full-rebuild ${CURRENT_REPO_INDEX_PROVENANCE_TOKEN}\``;
+        emit({ row: row2, warning });
+        return { repo, row: row2, warning, base, expectedActiveDigest };
       }
       if (targetCommit && targetCommit === base.commit) {
-        drift.push({ repo, reason: "healthy", action: "skip", activeCommit: base.commit, targetCommit });
-        skipped.push(`${repo}: unchanged verified-ready authority at ${targetCommit}`);
-        continue;
+        const row2 = { repo, reason: "healthy", action: "skip", activeCommit: base.commit, targetCommit };
+        const warning = `${repo}: unchanged verified-ready authority at ${targetCommit}`;
+        emit({ row: row2, warning });
+        return { repo, row: row2, warning, base, expectedActiveDigest };
       }
     }
-    drift.push({
+    const row = {
       repo,
       reason,
       action: "build",
       ...base ? { activeCommit: base.commit } : {},
       ...targetCommit ? { targetCommit } : {}
-    });
-    if (opts.plan) continue;
+    };
+    emit({ row });
+    return { repo, row, base, expectedActiveDigest };
+  });
+  for (const entry of classified) {
+    drift.push(entry.row);
+    if (entry.warning) skipped.push(entry.warning);
+    if (entry.row.action === "needs-full-rebuild") needsFullRebuild.push(entry.repo);
+  }
+  if (opts.plan) return answer();
+  for (const entry of classified) {
+    if (entry.row.action !== "build") continue;
+    const { repo, base, expectedActiveDigest } = entry;
     const dir = (0, import_node_fs27.mkdtempSync)((0, import_node_path25.join)((0, import_node_os13.tmpdir)(), "mmi-repo-index-"));
     try {
       shallowClone(repo, dir, opts.githubToken);
@@ -26534,6 +26623,79 @@ function runSpawnPolicy(root) {
 var import_node_child_process17 = require("node:child_process");
 var import_node_fs30 = require("node:fs");
 var import_node_path27 = require("node:path");
+
+// ../scripts/test-command-policy-core.mjs
+var TEST_COMMAND_CLASS = "test";
+function translateGlob(glob) {
+  let out = "";
+  for (let i = 0; i < glob.length; i += 1) {
+    const char = glob[i];
+    if (char === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") {
+          out += "(?:.*/)?";
+          i += 2;
+        } else {
+          out += ".*";
+          i += 1;
+        }
+      } else out += "[^/]*";
+    } else if (char === "{") {
+      const close = glob.indexOf("}", i);
+      if (close === -1) out += "\\{";
+      else {
+        out += `(?:${glob.slice(i + 1, close).split(",").map(translateGlob).join("|")})`;
+        i = close;
+      }
+    } else {
+      out += /[.+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
+    }
+  }
+  return out;
+}
+function globToRegExp(glob) {
+  return new RegExp(`^${translateGlob(glob)}$`);
+}
+function mandatoryGlobList(mandatory) {
+  if (!Array.isArray(mandatory)) return [];
+  return mandatory.map((entry) => typeof entry === "string" ? entry : entry?.glob).filter((glob) => typeof glob === "string");
+}
+function matchedMandatoryGlobs(paths, mandatory) {
+  const globs = mandatoryGlobList(mandatory);
+  const list = Array.isArray(paths) ? paths : [];
+  return globs.filter((glob) => {
+    const re = globToRegExp(glob);
+    return list.some((path2) => re.test(path2));
+  });
+}
+function evaluateTestCommandPolicy({ paths, mandatory, regulated = true } = {}) {
+  const configuredMandatoryCount = mandatoryGlobList(mandatory).length;
+  if (!regulated) {
+    return {
+      configuredMandatoryCount: 0,
+      matchedMandatoryGlobs: [],
+      matchedMandatoryCount: 0,
+      testCommandsAllowed: true,
+      reasonId: null,
+      commandClasses: { allowed: [TEST_COMMAND_CLASS], refused: [] }
+    };
+  }
+  const matched = matchedMandatoryGlobs(paths, mandatory);
+  const testCommandsAllowed = matched.length > 0;
+  return {
+    configuredMandatoryCount,
+    matchedMandatoryGlobs: matched,
+    matchedMandatoryCount: matched.length,
+    testCommandsAllowed,
+    reasonId: testCommandsAllowed ? null : "test-command-outside-mandatory-zone",
+    commandClasses: {
+      allowed: testCommandsAllowed ? [TEST_COMMAND_CLASS] : [],
+      refused: testCommandsAllowed ? [] : [TEST_COMMAND_CLASS]
+    }
+  };
+}
+
+// src/test-policy-core.ts
 var POLICY_FILE = "test-policy.json";
 var TEST_RE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
 var PY_TEST_RE = /(?:^|\/)test_[^/]*\.py$|_test\.py$/;
@@ -26579,7 +26741,7 @@ function translate(glob) {
   }
   return out;
 }
-function globToRegExp(glob) {
+function globToRegExp2(glob) {
   return new RegExp(`^${translate(glob)}$`);
 }
 function isTestPath(path2) {
@@ -26813,7 +26975,7 @@ function isMeaningfulChange(path2, before, after) {
   return !a.every((t, k) => t.text === b[k].text && t.nl === b[k].nl);
 }
 function annotateChangeMeaning(changed, policy, read) {
-  const matchers = (policy.mandatory ?? []).map((m) => globToRegExp(m.glob));
+  const matchers = (policy.mandatory ?? []).map((m) => globToRegExp2(m.glob));
   return changed.map((file) => {
     if (file.status !== "M" || !SUPPORTED_SOURCE.test(file.path)) return file;
     if (!matchers.some((re) => re.test(file.path)) && !isTestPath(file.path)) return file;
@@ -26851,7 +27013,7 @@ function removedPaths2(changed) {
   );
 }
 function classify(changed, policy, present = () => false) {
-  const matchers = (policy.mandatory ?? []).map((m) => ({ ...m, re: globToRegExp(m.glob) }));
+  const matchers = (policy.mandatory ?? []).map((m) => ({ ...m, re: globToRegExp2(m.glob) }));
   const mandatoryHits = changed.filter((f) => matchers.some((m) => m.re.test(f.path)));
   const testChanges = changed.filter((f) => isTestPath(f.path));
   const addedTests = testChanges.filter((f) => f.status === "A");
@@ -27101,7 +27263,23 @@ function runTestPolicy(root, deps = {}) {
   };
   const blocking = sift([...refusal ? [refusal] : [], ...lookup.refusals, ...staleFindings]);
   const findings = blocking.length > 0 ? blocking : sift(evaluate(changed, policy, present));
-  const result = { ok: findings.length === 0, findings, changedCount: changed.length, base, ...counts };
+  const commandPolicy = evaluateTestCommandPolicy({
+    paths: changed.map((f) => f.path),
+    mandatory: policy.mandatory,
+    regulated: policy.declared !== false
+  });
+  const result = {
+    ok: findings.length === 0,
+    findings,
+    changedCount: changed.length,
+    base,
+    ...counts,
+    matchedMandatoryGlobs: commandPolicy.matchedMandatoryGlobs,
+    matchedMandatoryCount: commandPolicy.matchedMandatoryCount,
+    testCommandsAllowed: commandPolicy.testCommandsAllowed,
+    testCommandReasonId: commandPolicy.reasonId,
+    commandClasses: commandPolicy.commandClasses
+  };
   if (override) {
     result.overriddenBy = override;
     result.waived = waived;
@@ -34448,15 +34626,68 @@ function formatExplainLoop(playbook) {
   }
   return lines.join("\n");
 }
-function explainCommandManifest(manifest, command) {
-  return {
+function catalogCommandPaths(manifest) {
+  const acc = [];
+  const walk2 = (command) => {
+    if (command.path) acc.push(command.path);
+    for (const child2 of command.subcommands) walk2(child2);
+  };
+  walk2(manifest.tree);
+  return acc;
+}
+function nearestExplainTargets(query, paths, limit = 5) {
+  const all = [...paths];
+  const leafOf = (p) => p.slice(p.lastIndexOf(" ") + 1);
+  const leaf = leafOf(query);
+  const exactLeaf = all.filter((p) => p !== query && leafOf(p) === leaf).sort();
+  if (exactLeaf.length) return exactLeaf.slice(0, limit);
+  const out = [];
+  const nearPath = didYouMean(query, all);
+  if (nearPath) out.push(nearPath);
+  const nearLeaf = didYouMean(leaf, new Set(all.map(leafOf)));
+  if (nearLeaf) {
+    for (const p of all.filter((candidate2) => leafOf(candidate2) === nearLeaf).sort()) {
+      if (!out.includes(p)) out.push(p);
+      if (out.length >= limit) break;
+    }
+  }
+  return out.slice(0, limit);
+}
+function explainCommandManifest(manifest, command, opts = {}) {
+  const base = {
     schema_version: 1,
     scope: "command",
     name: manifest.name,
-    ...manifest.version ? { version: manifest.version } : {},
+    ...manifest.version ? { version: manifest.version } : {}
+  };
+  if (!command.subcommands.length) {
+    return {
+      ...base,
+      command: { ...command, subcommands: [] }
+    };
+  }
+  if (opts.recursive) {
+    return {
+      ...base,
+      command: {
+        ...command,
+        subcommands: command.subcommands.map((child2) => ({ ...child2, subcommands: [] }))
+      }
+    };
+  }
+  return {
+    ...base,
     command: {
       ...command,
-      subcommands: command.subcommands.map((child2) => ({ ...child2, subcommands: [] }))
+      subcommands: []
+    },
+    children: command.subcommands.map((child2) => ({
+      path: child2.path,
+      ...child2.description ? { summary: child2.description } : {},
+      detail: `mmi-cli explain ${child2.path} --json`
+    })),
+    next: {
+      recursive: `mmi-cli explain ${command.path} --json --recursive`
     }
   };
 }
@@ -34472,7 +34703,7 @@ function findCommandInManifest(manifest, commandPath3) {
   return visit(manifest.tree);
 }
 function registerExplainCommand(program3) {
-  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).option("--json", "machine-readable focused command, route, or loop detail").action((commandArgs, opts) => {
+  program3.command("explain").description("print a command's purpose, flags, and examples from the live schema \u2014 one grounding call replaces trial-and-error").argument("[command...]", 'the command path to explain (e.g. "issue create")').addOption(new Option("--loop <name>", "print the canonical command sequence: agent | start-work | ship-pr | hotfix").choices(Object.keys(LOOP_PLAYBOOKS))).option("--json", "machine-readable focused command, route, or loop detail").option("--recursive", "include full schemas for immediate children (default: compact child index)").option("--full", "alias for --recursive").action((commandArgs, opts) => {
     if (opts.loop) {
       if (!LOOP_PLAYBOOKS[opts.loop]) {
         const valid = Object.keys(LOOP_PLAYBOOKS).join(", ");
@@ -34490,10 +34721,19 @@ function registerExplainCommand(program3) {
     const commandPath3 = commandArgs.join(" ");
     const command = findCommandInManifest(manifest, commandPath3);
     if (!command) {
-      fail(`explain: unknown command "${commandPath3}"`, { code: ERROR_CODES.ERR_NOT_FOUND });
+      const nearest = nearestExplainTargets(commandPath3, catalogCommandPaths(manifest));
+      fail(`explain: unknown command "${commandPath3}"`, {
+        code: ERROR_CODES.ERR_NOT_FOUND,
+        ...nearest.length ? {
+          expected: nearest,
+          did_you_mean: nearest[0],
+          corrected_command: `mmi-cli explain ${nearest[0]} --json`
+        } : {}
+      });
       return;
     }
-    console.log(opts.json ? JSON.stringify(explainCommandManifest(manifest, command), null, 2) : command.subcommands.length ? formatExplainGroup(command, manifest.name) : formatExplainCommand(command, manifest.name));
+    const recursive = Boolean(opts.recursive || opts.full);
+    console.log(opts.json ? JSON.stringify(explainCommandManifest(manifest, command, { recursive }), null, 2) : command.subcommands.length ? formatExplainGroup(command, manifest.name) : formatExplainCommand(command, manifest.name));
   });
 }
 
@@ -35504,6 +35744,7 @@ var surfaces_default = {
             targetPath: "packages/claude-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -35630,6 +35871,7 @@ var surfaces_default = {
             targetPath: "packages/codex-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -35748,6 +35990,7 @@ var surfaces_default = {
             targetPath: "packages/kimi-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -35874,6 +36117,7 @@ var surfaces_default = {
             targetPath: "packages/cursor-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -35996,6 +36240,7 @@ var surfaces_default = {
             targetPath: ".kilo-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -36105,6 +36350,7 @@ var surfaces_default = {
             targetPath: ".pi-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -36204,6 +36450,7 @@ var surfaces_default = {
             targetPath: "packages/hermes-plugin/scripts",
             include: [
               "pretooluse-shell-gates.mjs",
+              "test-command-policy-core.mjs",
               "vault-edit-gate.mjs",
               "deny-gate-crash.mjs",
               "secret-echo-lint.mjs",
@@ -38932,13 +39179,28 @@ function positionalTargetForm(cmd, opts = {}) {
   if (!first) return void 0;
   return formatPositionalTarget(canonicalPathFor(commandPath2(cmd)) ?? commandPath2(cmd), first.name(), opts);
 }
+function unknownCommandCandidates(parent, allPaths) {
+  if (!parent) return [...allPaths];
+  const scoped = parent.commands.length ? parent.commands.filter((child2) => commandMetadata(child2)?.category !== "internal").map(commandPath2) : [];
+  const house = houseForPath(commandPath2(parent));
+  const sameHouse = house ? allPaths.filter((p) => houseForPath(p) === house) : [...allPaths];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const p of [...scoped, ...sameHouse]) {
+    if (seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
 function resolveParseHint() {
   if (lastParseErrorKind === "unknown-command") {
     const parent = resolveCommandFromArgv(program2, process.argv.slice(2));
-    const candidates = parent && parent.commands.length ? parent.commands.filter((child2) => commandMetadata(child2)?.category !== "internal").map(commandPath2) : allCommandPaths();
+    const candidates = unknownCommandCandidates(parent, allCommandPaths());
     const path3 = lastUnknownCommand ? suggestCommandPath(lastUnknownCommand, candidates) : void 0;
     const canonical = path3 ? canonicalPathFor(path3) ?? path3 : void 0;
-    return canonical ? `(did you mean \`mmi-cli ${canonical}\`? ${DISCOVERY_HINT})` : STALE_HINT;
+    if (canonical) return `(did you mean \`mmi-cli ${canonical}\`? ${DISCOVERY_HINT})`;
+    return parent ? `(${DISCOVERY_HINT})` : STALE_HINT;
   }
   if (lastParseErrorKind !== "bad-arguments") return STALE_HINT;
   const cmd = resolveCommandFromArgv(program2, process.argv.slice(2));
@@ -39474,7 +39736,15 @@ repoIndex.command("gc").description("remove v4 cloud authority material for repo
       consoleIo.log(JSON.stringify(res, null, 2));
       return;
     }
-    console.log(`repo-index: gc removed ${res.removed.length} orphan v4 authority record(s)`);
+    let artifactsRemoved = 0;
+    let artifactsKept = 0;
+    for (const receipt of Object.values(res.v4.repos)) {
+      artifactsRemoved += receipt.removed.length;
+      artifactsKept += receipt.kept;
+    }
+    console.log(
+      `repo-index: gc tombstoned ${res.removed.length} orphan authorit${res.removed.length === 1 ? "y" : "ies"}, removed ${artifactsRemoved} artifact(s); kept ${res.kept} authorit${res.kept === 1 ? "y" : "ies"}, ${artifactsKept} artifact(s)`
+    );
   } catch (e) {
     return await failGraceful(e.message);
   }
@@ -39484,6 +39754,10 @@ repoIndex.command("sync-estate").description("Hub indexer: publish a pushed comm
     const cfg = await loadConfig();
     const gh = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "";
     if (!gh) await failGraceful("sync-estate needs GH_TOKEN or GITHUB_TOKEN with contents:read on target repos");
+    if (!o.json) {
+      console.log(`repo-index: pipeline provenance ${CURRENT_REPO_INDEX_PROVENANCE_TOKEN} \u2014 delta is the normal path${o.plan ? " (plan only: nothing was cloned, embedded or published)" : ""}`);
+    }
+    const streamedWarnings = /* @__PURE__ */ new Set();
     const res = await syncEstateRepoIndex({
       deps: registryClientDeps(cfg),
       repo: o.repo,
@@ -39491,26 +39765,30 @@ repoIndex.command("sync-estate").description("Hub indexer: publish a pushed comm
       fullRebuild: o.fullRebuild,
       skipRepos: o.skipRepo,
       plan: Boolean(o.plan),
-      githubToken: gh
+      githubToken: gh,
+      onClassify: o.json ? void 0 : ({ row, warning }) => {
+        const at = row.targetCommit ? ` target=${row.targetCommit.slice(0, 12)}` : "";
+        const active = row.activeCommit ? ` active=${row.activeCommit.slice(0, 12)}` : "";
+        console.log(`repo-index: ${row.repo} ${row.reason} \u2192 ${row.action}${active}${at}`);
+        if (warning) {
+          streamedWarnings.add(warning);
+          console.error(`repo-index: WARN ${warning}`);
+        }
+      }
     });
     if (o.json) {
       consoleIo.log(JSON.stringify(res, null, 2));
       if (!res.ok) process.exitCode = 1;
       return;
     }
-    console.log(`repo-index: pipeline provenance ${res.provenanceToken} \u2014 delta is the normal path${o.plan ? " (plan only: nothing was cloned, embedded or published)" : ""}`);
-    for (const row of res.drift) {
-      if (row.reason === "healthy") continue;
-      const at = row.targetCommit ? ` target=${row.targetCommit.slice(0, 12)}` : "";
-      const active = row.activeCommit ? ` active=${row.activeCommit.slice(0, 12)}` : "";
-      console.log(`repo-index: ${row.repo} ${row.reason} \u2192 ${row.action}${active}${at}`);
-    }
     for (const p of res.published) {
       const gap = p.embGap ?? Math.max(0, p.fileCount - (p.embCount ?? 0));
       console.log(`repo-index: published v4 ${p.repo} \u2014 ${p.fileCount} chunks emb=${p.embCount ?? 0}/${p.fileCount} gap=${gap} graph=${p.graphEdges ?? "unavailable"}`);
       if (p.metrics) console.log(`repo-index: ${formatV4BuildMetrics(p.repo, p.metrics)}`);
     }
-    for (const warning of res.skipped) console.error(`repo-index: WARN ${warning}`);
+    for (const warning of res.skipped) {
+      if (!streamedWarnings.has(warning)) console.error(`repo-index: WARN ${warning}`);
+    }
     if (res.needsFullRebuild.length) {
       console.error(`repo-index: ${res.needsFullRebuild.length} repo(s) need an explicit tokened migration: ${res.needsFullRebuild.join(", ")}`);
     }
@@ -39589,7 +39867,7 @@ spawnCmd.command("policy").description("enforce the windowsHide contract across
   }
 });
 var tests = program2.command("tests").description("a repo's test-policy.json \u2014 the opt-in test contract and its enforcement");
-tests.command("policy").description("enforce this repo's test-policy.json against the diff: a mandatory-zone change must carry a test, an unrequested new test file is refused, a `protected` test file may not be deleted or renamed away, and a `protected` entry naming a missing file is refused. Override any of them with a `Test-Policy-Override: <reason>` commit trailer (#3605)").option("--json", "machine-readable result: { ok, base, changedCount, findings[] }").option("--base <ref>", "comparison base (default: TEST_POLICY_BASE, then origin/development, then origin/main)").action(async (o) => {
+tests.command("policy").description("enforce this repo's test-policy.json against the diff: a mandatory-zone change must carry a test, an unrequested new test file is refused, a `protected` test file may not be deleted or renamed away, and a `protected` entry naming a missing file is refused. Override any of them with a `Test-Policy-Override: <reason>` commit trailer (#3605)").option("--json", "machine-readable result: { ok, base, changedCount, mandatoryCount, matchedMandatoryCount, matchedMandatoryGlobs, testCommandsAllowed, commandClasses, findings[] }").option("--base <ref>", "comparison base (default: TEST_POLICY_BASE, then origin/development, then origin/main)").action(async (o) => {
   try {
     const root = await repoRoot();
     const result = runTestPolicy(root, { base: o.base });
@@ -39605,8 +39883,9 @@ tests.command("policy").description("enforce this repo's test-policy.json agains
       return;
     }
     if (result.ok) {
+      const commandVerdict = result.testCommandsAllowed ? "test commands: allowed" : `test commands: refused [${result.testCommandReasonId}]`;
       console.log(
-        `tests policy: OK (${result.changedCount} changed file(s); ${result.mandatoryCount} mandatory glob(s), ${result.protectedCount} protected file(s)).`
+        `tests policy: OK (${result.changedCount} changed file(s); ${result.matchedMandatoryCount} of ${result.mandatoryCount} mandatory glob(s) matched, ${result.protectedCount} protected file(s); ${commandVerdict}).`
       );
       return;
     }
@@ -42085,5 +42364,6 @@ program2.parseAsync(process.argv).then(() => finishCliRun()).catch((e) => failGr
   positionalTargetForm,
   registryClientDeps,
   repoSlug,
-  suggestCommandPath
+  suggestCommandPath,
+  unknownCommandCandidates
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",