@mutmutco/cli 3.38.0 → 3.39.0

package/dist/main.cjs

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_PRIORITY: () => DEFAULT_PRIORITY,
   awsCallerArn: () => awsCallerArn,
+  classifyParseError: () => classifyParseError,
   gcPlan: () => gcPlan,
   isOrgRegisteredRepo: () => isOrgRegisteredRepo,
   registryClientDeps: () => registryClientDeps,
@@ -4763,6 +4764,13 @@ async function filterDependencyBlockedClaimables(items, client, opts = {}) {
   return { claimable, blocked, warnings };
 }
 
+// src/registry-degrade.ts
+function registryDegradeError(error) {
+  return new Error(
+    `Hub registry read failed (${error}) \u2014 board coords could not be discovered. This is NOT necessarily the registry: a local DNS/network fault reaches this path as a timeout too. Check in order \u2014 (1) resolve the Hub API host (fails in seconds and rules out the local-network class), (2) if it resolves, retry: a Lambda cold start clears shortly, (3) if it still fails, check auth (a rejected credential is not a timeout).`
+  );
+}
+
 // ../infra/registry-endpoints.mjs
 var PROJECTS_LIST_PATH = "/projects/list";
 var ORG_CONFIG_PATH = "/org/config";
@@ -6557,20 +6565,56 @@ async function fetchSecretsDrift(deps, repo) {
   if (!data || data.mode !== "drift") return null;
   return data.drift;
 }
-async function secretsOrgCatalogSet(deps, fileBody) {
-  let parsed;
+function formatOrgCatalog(entries) {
+  const keys = Object.keys(entries).sort();
+  if (!keys.length) return "org-infra catalog: no declarations";
+  const width = Math.max(...keys.map((k) => k.length));
+  const lines = keys.map((k) => {
+    const e = entries[k];
+    const stages = e.stages?.length ? e.stages.join(",") : "shared";
+    return `  ${k.padEnd(width)}  owner: ${e.owner}  stages: ${stages}  consumers: ${(e.consumers ?? []).join(",")}  \u2014 ${e.purpose}`;
+  });
+  return [
+    `org-infra secret catalog \u2014 ${keys.length} declaration(s) (_org/<provider>/<KEY>; declarations only, values never live here)`,
+    ...lines
+  ].join("\n");
+}
+function formatOrgCatalogOutcome(out) {
+  const verb = out.mode === "replace" ? "replaced" : "merged";
+  return `org-infra catalog ${verb}: ${out.added ?? 0} added, ${out.updated ?? 0} updated, ${out.unchanged ?? 0} unchanged, ${out.removed ?? 0} removed (${out.entries ?? "?"} entries total)`;
+}
+async function secretsOrgCatalogShow(deps, opts) {
+  let res;
   try {
-    parsed = JSON.parse(fileBody);
-  } catch {
-    deps.err('secrets org-catalog: file is not valid JSON ({ entries: { "<provider>/<KEY>": {...} } })');
+    res = await deps.fetch(`${deps.apiUrl}/catalog/org-infra`, {
+      method: "GET",
+      headers: await deps.headers(),
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+  } catch (e) {
+    deps.err(`secrets org-catalog: ${e.message}`);
+    return false;
+  }
+  if (!res.ok) {
+    deps.err(await upgradeMessage(res) ?? `secrets org-catalog failed: HTTP ${res.status}${await readErr(res)}`);
     return false;
   }
+  const cat = await res.json();
+  const entries = cat.entries ?? {};
+  if (opts.json) {
+    deps.log(JSON.stringify({ entries }, null, 2));
+    return true;
+  }
+  deps.log(formatOrgCatalog(entries));
+  return true;
+}
+async function postOrgCatalog(deps, payload) {
   let res;
   try {
     res = await deps.fetch(`${deps.apiUrl}/catalog/org-infra`, {
       method: "POST",
       headers: await deps.headers({ "content-type": "application/json" }),
-      body: JSON.stringify(parsed),
+      body: JSON.stringify(payload),
       signal: AbortSignal.timeout(TIMEOUT_MS)
     });
   } catch (e) {
@@ -6581,10 +6625,30 @@ async function secretsOrgCatalogSet(deps, fileBody) {
     deps.err(await upgradeMessage(res) ?? `secrets org-catalog failed: HTTP ${res.status}${await readErr(res)}`);
     return false;
   }
-  const out = await res.json();
-  deps.log(`org-infra catalog updated: ${out.entries ?? "?"} entries`);
+  deps.log(formatOrgCatalogOutcome(await res.json()));
   return true;
 }
+async function secretsOrgCatalogSet(deps, fileBody, opts = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fileBody);
+  } catch {
+    deps.err('secrets org-catalog: file is not valid JSON ({ entries: { "<provider>/<KEY>": {...} } })');
+    return false;
+  }
+  if (parsed && typeof parsed === "object" && ("mode" in parsed || "remove" in parsed)) {
+    deps.err('secrets org-catalog: the file carries { entries } only \u2014 use --replace / --remove flags, not "mode"/"remove" file fields');
+    return false;
+  }
+  return postOrgCatalog(deps, {
+    entries: parsed.entries,
+    ...opts.replace ? { mode: "replace" } : {},
+    ...opts.remove?.length ? { remove: opts.remove } : {}
+  });
+}
+async function secretsOrgCatalogRemove(deps, remove2) {
+  return postOrgCatalog(deps, { entries: {}, remove: remove2 });
+}
 var DEFAULT_RUNTIME_SECRET_NAMES = ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
 function stringList(v) {
   return Array.isArray(v) ? v.filter((x) => typeof x === "string" && isValidSecretKey(x)) : [];
@@ -6715,10 +6779,11 @@ async function putSecret(deps, key, value, opts) {
     return false;
   }
   const repo = await targetRepo(deps, opts);
+  const slug = opts.slug?.toLowerCase();
   const res = await deps.fetch(`${deps.apiUrl}/secrets/set`, {
     method: "POST",
     headers: await deps.headers({ "content-type": "application/json" }),
-    body: JSON.stringify({ repo, key, value }),
+    body: JSON.stringify({ repo, key, value, ...slug ? { slug } : {} }),
     signal: AbortSignal.timeout(TIMEOUT_MS)
   });
   if (!res.ok) {
@@ -6732,7 +6797,7 @@ async function putSecret(deps, key, value, opts) {
   const provider = providerForSecretKey(key);
   if (provider) {
     const result = await verifySecretValue(deps, key, value, opts);
-    const tier = classifyTier(await vaultSlug(deps, opts), key);
+    const tier = classifyTier(slug ?? await vaultSlug(deps, opts), key);
     if (result.ok) {
       deps.log(`set ${key} (${tier} tier); ${result.message}`);
       return true;
@@ -6745,7 +6810,7 @@ async function putSecret(deps, key, value, opts) {
     deps.err(`set ${key} (${tier} tier), but ${result.message}`);
     return false;
   }
-  deps.log(`set ${key} (${classifyTier(await vaultSlug(deps, opts), key)} tier)`);
+  deps.log(`set ${key} (${classifyTier(slug ?? await vaultSlug(deps, opts), key)} tier)`);
   return true;
 }
 async function secretsSet(deps, key, opts) {
@@ -7330,7 +7395,7 @@ async function loadConfigForBoardSelector(selector, repoOption) {
   if (!floor.sagaApiUrl) return stripMutableBoardConfig(floor);
   const slug = targetRepo2 ? slugOf(targetRepo2) : await repoSlug();
   const read = await fetchProjectBySlugChecked(slug, registryClientDeps(floor));
-  if (!read.ok) throw new Error(`Hub registry read failed (${read.error}) \u2014 board coords could not be discovered; likely transient (cold start, network, or auth blip) \u2014 retry shortly`);
+  if (!read.ok) throw registryDegradeError(read.error);
   return read.project ? boardConfigFromProject(read.project, floor) : stripMutableBoardConfig(floor);
 }
 
@@ -8878,6 +8943,7 @@ function commandLadderHint() {
     lines.push(`${e.gh.padEnd(pad)} \u2192 ${e.replacement}`);
   }
   lines.push("[mmi] Schedules doctrine (#3228): scheduled jobs + LLM crons go through the Hub registry \u2014 eight-field header \u2192 PR \u2192 `mmi-cli org schedules register`; LLM crons ONLY via the harbour (llm: yes \u21D2 executor cursor-agent). Never hand-build an unregistered cron. Opt out per repo: `mmi-cli org schedules mode self-managed`.");
+  lines.push('[mmi] Registering \u2260 armed (#3281): `org schedules register` writes SCHEDULE# rows; the fleet-clock reconciler arms them within ~15 min. Report "registered successfully \u2014 arms on the next fleet-clock tick", never "armed"/"live". The success JSON carries an `arming` block. Before that window an absent clock means "not reconciled yet", NOT "will never fire" \u2014 verify with `mmi-cli org schedules` after it.');
   return lines.join("\n");
 }
 
@@ -8903,6 +8969,40 @@ function resolveMergeCiPolicy(input) {
   }
   return { policy: "wait-for-checks", reason: ciWorkflows.join(", ") };
 }
+function describePrMergeEnqueuedReason(checks) {
+  switch (checks) {
+    case "pending":
+      return {
+        reason: "checks-pending",
+        message: "checks are still pending; auto-merge will land once they settle, so retry later is appropriate"
+      };
+    case "failure":
+      return {
+        reason: "checks-failing",
+        message: "GitHub reports a red check; auto-merge will not land until the required checks pass, so retrying now is pointless"
+      };
+    case "failing":
+      return {
+        reason: "checks-failing",
+        message: "GitHub reports a red check while others are still running; wait for checks to settle before retrying"
+      };
+    case "no-checks-reported":
+      return {
+        reason: "no-checks-reported",
+        message: "GitHub reports no checks; auto-merge remains queued until the base-branch policy permits the merge"
+      };
+    case "success":
+      return {
+        reason: "checks-passing",
+        message: "reported checks are passing, but the base-branch policy or merge queue has not completed the merge yet"
+      };
+    default:
+      return {
+        reason: "checks-unavailable",
+        message: "the current check verdict could not be read; auto-merge remains queued, so inspect checks before retrying"
+      };
+  }
+}
 function parseGhPrChecksOutput(stdout) {
   const text = stdout.trim();
   if (!text) return "no-checks-reported";
@@ -11317,14 +11417,27 @@ function buildPrArgs({ title, body, base, head, repo, draft }) {
   if (draft) args.push("--draft");
   return args;
 }
+function parseExistingPr(stderr) {
+  if (!/already exists/i.test(stderr)) return void 0;
+  const match = /https:\/\/\S*\/pull\/(\d+)/.exec(stderr);
+  if (!match) return void 0;
+  return { number: Number(match[1]), url: match[0] };
+}
 async function ghCreate(args) {
   const swapped = await bodyArgsViaFile(args);
   try {
     const { stdout } = await execFileP2("gh", swapped.args, { timeout: GH_MUTATION_TIMEOUT_MS });
     return parseCreatedUrl(stdout);
   } catch (e) {
-    await swapped.cleanup();
     const err = e;
+    const existing = parseExistingPr(`${err.stderr ?? ""}
+${err.message ?? ""}`);
+    if (existing) {
+      await swapped.cleanup();
+      console.warn(`${args[0]} create: a PR already exists for this branch \u2014 #${existing.number} (nothing to do)`);
+      return { ...existing, existing: true };
+    }
+    await swapped.cleanup();
     const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
     fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}${note ? ` (${note})` : ""}`);
   } finally {
@@ -16416,14 +16529,31 @@ function registerSecretsCommands(program3) {
     });
     if (!report.ok) process.exitCode = 1;
   });
-  secrets.command("org-catalog").description("MASTER-ONLY: set the _org/<provider>/* catalog declarations from a JSON file (#2244)").requiredOption("--file <path>", 'JSON file: { "entries": { "<provider>/<KEY>": {key,purpose,group,owner,provider,stages[],consumers[]} } }').action((o) => withSecrets(async (d) => {
+  secrets.command("org-catalog").description("the _org/<provider>/* catalog declarations (#2244) \u2014 --show reads (any org member); writes are master-only and MERGE by default (#3297)").option("--show", "print the stored catalog (declarations only \u2014 names, purpose, owner; never values)").option("--json", "--show output as the exact { entries } JSON shape --file accepts (lossless read-edit-write round-trip)").option("--file <path>", 'JSON file: { "entries": { "<provider>/<KEY>": {key,purpose,group,owner,provider,stages[],consumers[]} } } \u2014 merged into the stored catalog').option("--replace", "DESTRUCTIVE: replace the whole catalog with --file exactly (requires --yes)").option("--remove <provider/KEY>", "delete one declaration from the stored catalog (repeatable)", collectMap, []).option("--yes", "confirm the destructive --replace").action((o) => withSecrets(async (d) => {
+    if (o.show) {
+      if (o.file || o.replace || o.remove?.length) return fail("secrets org-catalog: --show does not combine with --file/--replace/--remove");
+      if (!await secretsOrgCatalogShow(d, { json: o.json })) process.exitCode = 1;
+      return;
+    }
+    if (o.replace) {
+      if (!o.file) return fail("secrets org-catalog: --replace needs --file (the complete catalog to write)");
+      if (!o.yes) {
+        return fail("secrets org-catalog --replace is DESTRUCTIVE \u2014 it deletes every declaration absent from the file (the #3297 data-loss form). Re-run with --yes to confirm; prefer the default merge, or --remove <provider/KEY> to delete one declaration.");
+      }
+    }
+    if (!o.file && !o.remove?.length) {
+      return fail("secrets org-catalog: nothing to do \u2014 pass --show, --file <path> (merged by default), or --remove <provider/KEY>");
+    }
     let body;
-    try {
-      body = (0, import_node_fs18.readFileSync)((0, import_node_path16.resolve)(o.file), "utf8");
-    } catch (e) {
-      return fail(`secrets org-catalog: cannot read --file ${o.file}: ${e.message}`);
+    if (o.file) {
+      try {
+        body = (0, import_node_fs18.readFileSync)((0, import_node_path16.resolve)(o.file), "utf8");
+      } catch (e) {
+        return fail(`secrets org-catalog: cannot read --file ${o.file}: ${e.message}`);
+      }
     }
-    if (!await secretsOrgCatalogSet(d, body)) process.exitCode = 1;
+    const ok = body !== void 0 ? await secretsOrgCatalogSet(d, body, { replace: o.replace, remove: o.remove }) : await secretsOrgCatalogRemove(d, o.remove ?? []);
+    if (!ok) process.exitCode = 1;
   }));
   secrets.command("preflight").description("check required stage secret names for a deploy/train without reading values").requiredOption("--stage <dev|rc|main>", "stage to check").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--required <KEY...>", "required keys; bare keys are scoped under --stage").option("--skip-compose-guard", "skip the #2813 fileless-compose \u2194 DEPLOY#.noEnvFile promotion guard").option("--json", "machine-readable output").action(async (o) => {
     if (!["dev", "rc", "main"].includes(o.stage)) {
@@ -16496,7 +16626,7 @@ function registerSecretsCommands(program3) {
     const ok = await secretsSet(d, key, o);
     if (!ok) process.exitCode = 1;
   });
-  secrets.command("set <key>").description("write/rotate a secret; value from stdin (never an argument). DECLARE-FIRST (#2528): the key must be a declared catalog coordinate \u2014 bare <KEY> = the stageless canonical, <stage>/<KEY> = a declared per-stage override; undeclared writes are rejected with the fix").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(setHandler);
+  secrets.command("set <key>").description("write/rotate a secret; value from stdin (never an argument). DECLARE-FIRST (#2528): the key must be a declared catalog coordinate \u2014 bare <KEY> = the stageless canonical, <stage>/<KEY> = a declared per-stage override; undeclared writes are rejected with the fix. --slug _org writes an org-infra <provider>/<KEY> coordinate (#3298) \u2014 master or an exact grant, declare-first enforced server-side").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--slug <slug>", "org-infra namespace (e.g. _org) for the value write \u2014 master or an exact grant (#3298)").action(setHandler);
   secrets.command("copy").description("copy provider keys between stages in your own project vault (audit-logged; encryption keys blocked)").requiredOption("--from <stage>", "source tier: dev, rc, or main").requiredOption("--to <stage>", "destination tier: dev, rc, or main").requiredOption("--keys <names>", "comma-separated secret names (encryption keys blocked)").option("--dry-run", "report copies without writing").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((o) => withSecrets(async (d) => {
     const stages = ["dev", "rc", "main"];
     if (!stages.includes(o.from) || !stages.includes(o.to)) {
@@ -16642,7 +16772,7 @@ async function mintInstallationToken(deps) {
   }
   return { token: body.token, expiresAt: body.expires_at };
 }
-async function activateAppActor(commandPath2, env, mint) {
+async function activateAppActor(commandPath3, env, mint) {
   const requested = (env[APP_ACTOR_ENV] ?? "").trim();
   if (!requested) return "personal";
   if (requested !== "app") {
@@ -16650,8 +16780,8 @@ async function activateAppActor(commandPath2, env, mint) {
   }
   delete env.GH_TOKEN;
   delete env.GITHUB_TOKEN;
-  if (!APP_ELIGIBLE_COMMANDS.has(commandPath2)) {
-    throw new AppActorError(`app actor: '${commandPath2}' is personal-only \u2014 App identity would break viewer/@me/authorship semantics; unset ${APP_ACTOR_ENV} for this command`);
+  if (!APP_ELIGIBLE_COMMANDS.has(commandPath3)) {
+    throw new AppActorError(`app actor: '${commandPath3}' is personal-only \u2014 App identity would break viewer/@me/authorship semantics; unset ${APP_ACTOR_ENV} for this command`);
   }
   const minted = await mint();
   env.GH_TOKEN = minted.token;
@@ -16975,9 +17105,17 @@ function awsScheduleEntry(payload) {
   if (typeof Name !== "string" || typeof ScheduleExpression !== "string") return null;
   if (State !== "ENABLED" || isJervResource(Name)) return null;
   let target = "";
+  let scheduleId;
   if (Target && typeof Target === "object") {
-    const { Arn } = Target;
+    const { Arn, Input } = Target;
     if (typeof Arn === "string") target = Arn.split(":").pop() ?? "";
+    if (typeof Input === "string") {
+      try {
+        const parsed = JSON.parse(Input);
+        if (typeof parsed?.scheduleId === "string" && parsed.scheduleId) scheduleId = parsed.scheduleId;
+      } catch {
+      }
+    }
   }
   return {
     name: Name,
@@ -16985,7 +17123,8 @@ function awsScheduleEntry(payload) {
     executor: target ? `aws-scheduler \u2192 ${target}` : "aws-scheduler",
     llm: readLlmDeclaration(typeof Description === "string" ? Description : void 0),
     resolved: "live",
-    source: `aws scheduler schedule ${Name} (eu-central-1)`
+    source: `aws scheduler schedule ${Name} (eu-central-1)`,
+    ...scheduleId ? { scheduleId } : {}
   };
 }
 function awsScheduleRefs(payload) {
@@ -17153,7 +17292,28 @@ function unlauncheredLlmDrifts(entries) {
   }
   return drifts.sort((a, b) => a.name.localeCompare(b.name));
 }
-function assembleReconciliation(githubEntries2, readRepos, registry2, activeWorkflowNames = /* @__PURE__ */ new Set()) {
+var HARBOUR_ARM_GRACE_MS = 30 * 60 * 1e3;
+function registeredButUnarmedDrifts(registry2, liveEntries, opts) {
+  if (!opts.schedulerRead) return [];
+  const now = opts.now ?? Date.now();
+  const armed = new Set(liveEntries.map((e) => e.scheduleId).filter((id) => Boolean(id)));
+  const drifts = [];
+  for (const row of registry2) {
+    if (row.executor === "github-actions") continue;
+    if (armed.has(row.id)) continue;
+    const stamped = row.updatedAt ? Date.parse(row.updatedAt) : NaN;
+    if (Number.isFinite(stamped) && now - stamped < HARBOUR_ARM_GRACE_MS) continue;
+    drifts.push({
+      class: "registered-but-unarmed",
+      name: row.id,
+      executor: row.executor,
+      detail: "registered as a harbour lane but no aws-scheduler clock dispatches it \u2014 it will never fire",
+      remedy: "check the fleet-clock reconciler tick; re-run `mmi-cli org schedules register` for the repo and verify with `mmi-cli org schedules`"
+    });
+  }
+  return drifts.sort((a, b) => a.name.localeCompare(b.name));
+}
+function assembleReconciliation(githubEntries2, readRepos, registry2, activeWorkflowNames = /* @__PURE__ */ new Set(), harbour = {}) {
   if (registry2 === null) {
     return {
       reconciliation: [],
@@ -17162,7 +17322,13 @@ function assembleReconciliation(githubEntries2, readRepos, registry2, activeWork
     };
   }
   const live = githubEntries2.filter((e) => e.executor === "github-actions");
-  const drifts = reconcileGithubActions(live, registry2, readRepos, activeWorkflowNames);
+  const drifts = [
+    ...reconcileGithubActions(live, registry2, readRepos, activeWorkflowNames),
+    ...registeredButUnarmedDrifts(registry2, harbour.awsEntries ?? [], {
+      schedulerRead: Boolean(harbour.schedulerRead),
+      now: harbour.now
+    })
+  ];
   return { reconciliation: drifts, driftLines: drifts.map(renderDrift), incomplete: [] };
 }
 
@@ -17275,6 +17441,7 @@ async function awsEntries() {
   } catch (e) {
     incomplete.push(`aws: events list-rules failed \u2014 ${e.message}`);
   }
+  let schedulerRead = false;
   try {
     const refs = awsScheduleRefs(await awsJson(["scheduler", "list-schedules"]));
     for (const ref of refs) {
@@ -17282,11 +17449,12 @@ async function awsEntries() {
       const entry = awsScheduleEntry(await awsJson(args));
       if (entry) entries.push(entry);
     }
+    schedulerRead = true;
   } catch (e) {
     incomplete.push(`aws: scheduler listing failed \u2014 ${e.message}`);
   }
   const reconciliation = unlauncheredLlmDrifts(entries);
-  return { entries, incomplete, drift: reconciliation.map(renderDrift), reconciliation };
+  return { entries, incomplete, drift: reconciliation.map(renderDrift), reconciliation, schedulerRead };
 }
 async function defaultRegistryRead() {
   return fetchSchedulesList(registryClientDeps(await loadConfig()));
@@ -17298,7 +17466,11 @@ async function fetchNotebook(client = defaultGitHubClient(), readRegistry = defa
     readRegistry().catch(() => null),
     readProjects().catch(() => null)
   ]);
-  const recon = assembleReconciliation(gh.entries, new Set(gh.readRepos), registry2, new Set(gh.workflowNames));
+  const recon = assembleReconciliation(gh.entries, new Set(gh.readRepos), registry2, new Set(gh.workflowNames), {
+    // #3286: the harbour side joins registry rows against the live aws-scheduler clocks by scheduleId.
+    awsEntries: aws.entries,
+    schedulerRead: Boolean(aws.schedulerRead)
+  });
   const selfManaged = /* @__PURE__ */ new Set();
   for (const proj of projects ?? []) {
     if (proj?.schedulesMode !== "self-managed") continue;
@@ -17541,17 +17713,33 @@ async function runSchedulesLift(opts, deps = {}) {
   }
   return { repo, records, payload, response };
 }
+var FLEET_CLOCK_RECONCILE_WINDOW = "~15 minutes";
+var ARMING_IS_EVENTUAL_NOTE = `  registered \u2014 not yet armed. The fleet-clock reconciler arms SCHEDULE# rows on its next tick (${FLEET_CLOCK_RECONCILE_WINDOW}).
+  Verify with \`mmi-cli org schedules\` after that window; an empty result before it means "not reconciled yet", not "will never fire".`;
+var ARMING_REPORT = {
+  armed: false,
+  state: "pending-reconcile",
+  withinMinutes: 15,
+  verifyWith: "mmi-cli org schedules",
+  report: "registered successfully \u2014 arms on the next fleet-clock tick, not yet",
+  note: `SCHEDULE# rows are written now; the fleet-clock reconciler arms them within ${FLEET_CLOCK_RECONCILE_WINDOW}. Before that window an absent clock means "not reconciled yet", NOT "will never fire" \u2014 do not report this as armed, live, or failed.`
+};
+function withArmingReport(body) {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return body;
+  return { ...body, arming: ARMING_REPORT };
+}
 function registerSchedulesLiftCommand(program3, deps = {}) {
   const schedules = program3.commands.find((c) => c.name() === "schedules");
   if (!schedules) throw new Error("schedules lift: registerSchedulesCommands must run first \u2014 the lift attaches to the `schedules` command");
-  schedules.command("register").alias("lift").description("register this repo's eight-field workflow headers as SCHEDULE# registry rows (C2, #3186; renamed from `lift`, #3219) \u2014 a per-repo replace; aborts the whole registration on any header violation; exits 75 when the registry is unreachable (#3187)").option("--repo <name>", "bare repo name for the join key (defaults to the origin remote basename, case-preserved)").option("--dir <path>", "workflows directory to lift (defaults to .github/workflows)").option("--dry-run", "print the {repo, schedules} body that would be POSTed; never write").action(async (o) => {
+  schedules.command("register").alias("lift").description(`register this repo's eight-field workflow headers as SCHEDULE# registry rows (C2, #3186; renamed from \`lift\`, #3219) \u2014 a per-repo replace; aborts the whole registration on any header violation; exits 75 when the registry is unreachable (#3187). Registering does NOT arm the clock: the fleet-clock reconciler arms the rows within ${FLEET_CLOCK_RECONCILE_WINDOW}, and the success JSON carries an \`arming\` block saying so (#3281)`).option("--repo <name>", "bare repo name for the join key (defaults to the origin remote basename, case-preserved)").option("--dir <path>", "workflows directory to lift (defaults to .github/workflows)").option("--dry-run", "print the {repo, schedules} body that would be POSTed; never write").action(async (o) => {
     try {
       const result = await runSchedulesLift({ repo: o.repo, dir: o.dir, dryRun: Boolean(o.dryRun) }, deps);
       if (o.dryRun) {
         console.log(JSON.stringify(result.payload, null, 2));
         return;
       }
-      console.log(JSON.stringify(result.response?.body));
+      console.log(JSON.stringify(withArmingReport(result.response?.body)));
+      console.error(ARMING_IS_EVENTUAL_NOTE);
     } catch (e) {
       const err = e;
       if (err instanceof RegistryUnreachableError) {
@@ -19286,9 +19474,6 @@ function registerStageCommands(program3) {
 
 // src/config-load.ts
 var discoveredConfig = null;
-function registryDegradeError(error) {
-  return new Error(`Hub registry read failed (${error}) \u2014 board coords could not be discovered; likely transient (cold start, network, or auth blip) \u2014 retry shortly`);
-}
 async function loadConfigOrDiscover() {
   if (discoveredConfig) return discoveredConfig;
   const floor = await loadConfig();
@@ -21231,6 +21416,17 @@ async function applyPluginHeal(surface, log, opts) {
   }
   return true;
 }
+async function healClaudePluginForDoctor(surface = detectSurface(process.env)) {
+  if (surfaceToken(surface) !== "claude") {
+    return { ok: false, detail: `not a Claude surface (${surface}) \u2014 no Hub-shipped plugin to reinstall` };
+  }
+  const steps = [];
+  const ok = await applyPluginHeal(surface, (msg) => steps.push(msg.trim()));
+  return {
+    ok,
+    detail: ok ? "marketplace remove \u2192 add \u2192 install succeeded" : `\`claude plugin\` reinstall failed or was skipped${steps.length ? ` (${steps[steps.length - 1]})` : ""}`
+  };
+}
 async function runGuard(readOrigin) {
   try {
     const surface = detectSurface(process.env);
@@ -21766,9 +21962,9 @@ function formatExplainLoop(playbook) {
   }
   return lines.join("\n");
 }
-function findCommandInManifest(manifest, commandPath2) {
+function findCommandInManifest(manifest, commandPath3) {
   const visit = (command) => {
-    if (command.path === commandPath2) return command;
+    if (command.path === commandPath3) return command;
     for (const child2 of command.subcommands) {
       const found = visit(child2);
       if (found) return found;
@@ -21793,10 +21989,10 @@ function registerExplainCommand(program3) {
       console.log(formatManifestHuman(manifest));
       return;
     }
-    const commandPath2 = commandArgs.join(" ");
-    const command = findCommandInManifest(manifest, commandPath2);
+    const commandPath3 = commandArgs.join(" ");
+    const command = findCommandInManifest(manifest, commandPath3);
     if (!command) {
-      fail(`explain: unknown command "${commandPath2}"`, { code: ERROR_CODES.ERR_NOT_FOUND });
+      fail(`explain: unknown command "${commandPath3}"`, { code: ERROR_CODES.ERR_NOT_FOUND });
       return;
     }
     console.log(command.subcommands.length ? formatExplainGroup(command, manifest.name) : formatExplainCommand(command, manifest.name));
@@ -22425,6 +22621,11 @@ function checkRepoWorktrees(probe) {
     ]
   };
 }
+function pluginHealTrigger(probe) {
+  if (probe.guardState === "no-install" || probe.guardState === "unresolved") return "unresolved";
+  const behind = Boolean(probe.installed && probe.released) && compareVersions(probe.installed, probe.released) < 0;
+  return behind ? "behind" : null;
+}
 function checkClaudePlugin(probe) {
   const { installed, released, guardState } = probe;
   const evidence = [
@@ -22432,20 +22633,22 @@ function checkClaudePlugin(probe) {
     `released:  ${released ?? "(not checked \u2014 offline or --fast)"}`,
     `resolvable: ${guardState}`
   ];
-  if (guardState === "no-install" || guardState === "unresolved") {
+  const trigger = pluginHealTrigger(probe);
+  if (trigger === "unresolved") {
     return {
       ok: false,
       label: guardState === "no-install" ? "Claude plugin \u2014 not installed" : "Claude plugin \u2014 unresolved (marketplace/cache missing)",
-      fix: "run `mmi-cli plugin heal` to reinstall the MMI marketplace + plugin, then restart Claude",
+      fix: "run `mmi-cli doctor --apply` (or `mmi-cli plugin heal`) to reinstall the MMI marketplace + plugin, then restart Claude",
       verbose: evidence
     };
   }
-  const behind = Boolean(installed && released) && compareVersions(installed, released) < 0;
-  if (behind) {
+  if (trigger === "behind") {
     return {
       ok: false,
       label: `Claude plugin ${installed} \u2192 ${released}`,
-      fix: "run /plugin, update MMI (reinstall if it shows a legacy row), then restart Claude",
+      // Name the CLI verb that actually fixes it, like every other red row — `/plugin` is the manual
+      // fallback, not the first resort (#3282).
+      fix: "run `mmi-cli doctor --apply` (or `mmi-cli plugin heal`) to reinstall it, then restart Claude",
       verbose: evidence
     };
   }
@@ -22597,9 +22800,34 @@ async function runDoctorClean(opts, io, deps) {
       checks.push({ ok: false, label: "gitignore block", fix: "run `mmi-cli doctor --apply` to write the org-managed .gitignore block", verbose: giEvidence });
     }
   }
-  const plugin = checkClaudePlugin({ installed, released, guardState: deps.pluginGuardState(isOrgRepo) });
-  checks.push(plugin);
-  if (!plugin.ok) restartPending = true;
+  const pluginProbe = { installed, released, guardState: deps.pluginGuardState(isOrgRepo) };
+  const healTrigger = pluginHealTrigger(pluginProbe);
+  if (apply && deps.healPlugin && healTrigger) {
+    const heal = await deps.healPlugin();
+    const label = healTrigger === "behind" ? `Claude plugin ${installed} \u2192 ${released}` : "Claude plugin \u2014 reinstalled";
+    const healEvidence = [
+      `installed: ${installed ?? "(none)"}`,
+      `released:  ${released ?? "(not checked \u2014 offline or --fast)"}`,
+      `resolvable: ${pluginProbe.guardState}`,
+      `heal: ${heal.detail}`
+    ];
+    checks.push(heal.ok ? {
+      ok: true,
+      label,
+      detail: "reinstalled via the MMI marketplace (remove \u2192 add \u2192 install)",
+      verbose: healEvidence
+    } : {
+      ok: false,
+      label,
+      fix: `auto-heal failed (${heal.detail}) \u2014 run \`mmi-cli plugin heal\`, then restart Claude`,
+      verbose: healEvidence
+    });
+    restartPending = true;
+  } else {
+    const plugin = checkClaudePlugin(pluginProbe);
+    checks.push(plugin);
+    if (!plugin.ok) restartPending = true;
+  }
   const cliInput = { currentVersion: deps.currentCliVersion(), releasedVersion: released };
   const cliReport = buildVersionLagReport(cliInput);
   if (apply && deps.updateCli && versionAutoUpdateAction(cliReport) === "npm") {
@@ -22826,6 +23054,9 @@ function mmiDoctorDeps() {
     releasedVersion: fetchNpmReleasedVersion,
     // #3272: the --apply self-heal for a stale running CLI — npm global, shadows any plugin shim (#2879).
     updateCli: npmSelfUpdateCli,
+    // #3282: the --apply self-heal for a stale/unresolved Claude plugin — the same marketplace reinstall
+    // `mmi-cli plugin heal` drives. Takes effect on the next Claude reload, so the row asks for a restart.
+    healPlugin: () => healClaudePluginForDoctor(),
     currentCliVersion: resolveClientVersion,
     readGitignore,
     writeGitignore,
@@ -22926,8 +23157,57 @@ function argvWantsJson2() {
   return process.argv.some((a) => a === "--json" || a.startsWith("--json="));
 }
 var unknownFlagJsonHandled = false;
+var PARSE_HINT_SENTINEL = "@@mmi-parse-hint@@";
+var DISCOVERY_HINT = "run `mmi-cli commands` for the agentic-coding map, `mmi-cli explain <command>` for detail, or `mmi-cli commands --json --primary` for machine discovery";
+var STALE_HINT = `(${DISCOVERY_HINT}). If you expected this command to exist, your installed mmi-cli may be stale \u2014 update it (see: mmi-cli doctor)`;
+var lastParseErrorKind = "other";
+function classifyParseError(plain) {
+  if (/unknown command/i.test(plain)) return "unknown-command";
+  if (/unknown option|missing required argument|too many arguments|argument missing/i.test(plain)) {
+    return "bad-arguments";
+  }
+  return "other";
+}
+function resolveCommandFromArgv(root, argv) {
+  let current = root;
+  for (const token of argv) {
+    if (token.startsWith("-")) break;
+    const next = current.commands.find(
+      (c) => c.name() === token || c.aliases().includes(token)
+    );
+    if (!next) break;
+    current = next;
+  }
+  return current === root ? void 0 : current;
+}
+function commandPath2(cmd) {
+  const parts = [];
+  let node = cmd;
+  while (node && node.parent) {
+    parts.unshift(node.name());
+    node = node.parent;
+  }
+  return parts.join(" ");
+}
+function resolveParseHint() {
+  if (lastParseErrorKind !== "bad-arguments") return STALE_HINT;
+  const cmd = resolveCommandFromArgv(program2, process.argv.slice(2));
+  if (!cmd) return `(${DISCOVERY_HINT})`;
+  const path2 = commandPath2(cmd);
+  return [
+    `Usage: mmi-cli ${path2} ${cmd.usage()}`,
+    "This command exists and your mmi-cli is not the problem \u2014 the ARGUMENTS did not parse.",
+    `Run \`mmi-cli ${path2} --help\` for its signature, \`mmi-cli explain ${path2}\` for detail, or \`mmi-cli commands\` for the full map.`
+  ].join("\n");
+}
 function envelopeAwareWriteErr(str) {
   const plain = str.replace(/\[[0-9;]*m/g, "");
+  if (plain.includes(PARSE_HINT_SENTINEL)) {
+    if (unknownFlagJsonHandled && argvWantsJson2()) return;
+    process.stderr.write(str.replace(PARSE_HINT_SENTINEL, resolveParseHint()));
+    return;
+  }
+  lastParseErrorKind = classifyParseError(plain);
   const match = /unknown option '([^']+)'/.exec(plain);
   if (match) {
     const flag = match[1];
@@ -22952,7 +23232,7 @@ function envelopeAwareWriteErr(str) {
   process.stderr.write(str);
 }
 var program2 = new Command();
-program2.name("mmi-cli").description("MMI Future Hub CLI \u2014 the org control plane for agentic coding.").version(resolveClientVersion()).configureOutput({ writeErr: envelopeAwareWriteErr }).showHelpAfterError("(run `mmi-cli commands` for the agentic-coding map, `mmi-cli explain <command>` for detail, or `mmi-cli commands --json --primary` for machine discovery). If you expected this command to exist, your installed mmi-cli may be stale \u2014 update it (see: mmi-cli doctor)");
+program2.name("mmi-cli").description("MMI Future Hub CLI \u2014 the org control plane for agentic coding.").version(resolveClientVersion()).configureOutput({ writeErr: envelopeAwareWriteErr }).showHelpAfterError(PARSE_HINT_SENTINEL);
 function appActorDeps() {
   return {
     fetchSecret: async (key) => fetchSecretValue(makeSecretsDeps(await loadConfig()), key, { repo: APP_VAULT_REPO }),
@@ -24420,7 +24700,7 @@ pr.command("land <number>").description("agent merge path (#1440): train probe \
   }
   if (result.status === "failed" || result.cleanupError) process.exitCode = 1;
 });
-pr.command("merge <number>").description("merge a PR (squash by default) and clean up its branch + worktree \u2014 no leftover local branch; on no-ci repos run pr ci-policy / checks-wait first (#1432)").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)").option("--auto", "enable auto-merge \u2014 merge once the base-branch policy is satisfied (use for policy-gated repos)").option("--preserve-worktree", "keep the local PR worktree/stage/branch for an active multi-issue batch (#1888)").option("--force", "acknowledge and merge past a remaining prunable/severe scratch housekeeping block (advisory kept plans/ never blocks, #3012)").action(async (number, o) => {
+pr.command("merge <number>").description("merge a PR (squash by default) and clean up its branch + worktree \u2014 no leftover local branch; on no-ci repos run pr ci-policy / checks-wait first (#1432)").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)").option("--auto", "enable auto-merge \u2014 merge once the base-branch policy is satisfied (use for policy-gated repos)").option("--wait", `wait for checks to reach a terminal passing verdict before merging (default budget ${PR_CHECKS_TIMEOUT_MS / 6e4}m)`).option("--preserve-worktree", "keep the local PR worktree/stage/branch for an active multi-issue batch (#1888)").option("--force", "acknowledge and merge past a remaining prunable/severe scratch housekeeping block (advisory kept plans/ never blocks, #3012)").action(async (number, o) => {
   const method = o.rebase ? "--rebase" : o.merge ? "--merge" : "--squash";
   const repoArgs = o.repo ? ["--repo", o.repo] : [];
   const [headRef, baseRef, headRefOid] = (await execFileP2("gh", ["pr", "view", number, ...repoArgs, "--json", "headRefName,baseRefName,headRefOid", "--jq", '.headRefName + " " + .baseRefName + " " + (.headRefOid // "")'], { timeout: GC_GH_TIMEOUT_MS2 })).stdout.trim().split(/\s+/);
@@ -24431,6 +24711,25 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
     (await execFileP2("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS }).catch(() => ({ stdout: "" }))).stdout
   );
   const ciPolicy = await resolveMergeCiPolicyForCheckout(o.repo);
+  if (o.wait) {
+    const repo = await requireRepo(o.repo);
+    const baseBranch = await fetchRestPrSnapshot(number, repo).then((s) => s.baseRef).catch(() => "development");
+    const wait = await waitForPrChecks({
+      resolvePolicy: () => resolveMergeCiPolicyForCheckout(o.repo),
+      pollChecks: () => pollRestPrChecks(number, repo),
+      pollMergeable: () => pollRestPrMergeable(number, repo),
+      pollRateLimit: () => fetchRestCorePool(),
+      baseBranch,
+      sleep: (ms) => new Promise((resolve5) => setTimeout(resolve5, ms)),
+      log: (message) => console.warn(message),
+      progress: ({ state, elapsedMs, remainingMs }) => console.warn(`pr merge: --wait checks \u2014 ${state}, ${Math.round(elapsedMs / 1e3)}s elapsed, ${Math.round(remainingMs / 6e4)}m left`)
+    });
+    if (wait.status !== "success" && wait.status !== "skipped") {
+      console.warn(`pr merge: --wait stopped before merge \u2014 ${wait.status}${wait.reason ? `: ${wait.reason}` : ""}${wait.detail ? ` (${wait.detail})` : ""}`);
+      process.exitCode = wait.status === "timeout" || wait.status === "rate-limited" ? PR_CHECKS_TIMEOUT_EXIT_CODE : 1;
+      return;
+    }
+  }
   if (ciPolicy.policy === "no-ci") {
     const guard = decidePrMergeNoCiGuard(await pollGhPrChecks(number, repoArgs), ciPolicy.reason);
     if (guard.action === "refuse") throw new Error(`gh pr merge ${number}: ${guard.message}`);
@@ -24481,9 +24780,11 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
   if (o.auto || upgradedToAuto) {
     const state = (await execFileP2("gh", ["pr", "view", number, ...repoArgs, "--json", "state", "--jq", ".state"], { timeout: GC_GH_TIMEOUT_MS2 }).catch(() => ({ stdout: "" }))).stdout.trim();
     if (state !== "MERGED") {
-      console.log(JSON.stringify({ mergeStatus: "auto-merge-enqueued", pr: number, branch: headRef, state: state || "unknown", upgradedToAuto: upgradedToAuto || void 0 }));
+      const enqueued = describePrMergeEnqueuedReason(await pollGhPrChecks(number, repoArgs).catch(() => void 0));
+      console.log(JSON.stringify({ mergeStatus: "auto-merge-enqueued", enqueuedReason: enqueued.reason, pr: number, branch: headRef, state: state || "unknown", upgradedToAuto: upgradedToAuto || void 0 }));
+      console.warn(`pr merge: PR #${number} is ENQUEUED, not merged \u2014 ${enqueued.message}.`);
       if (upgradedToAuto && !o.auto) {
-        console.warn(`pr merge: PR #${number} is ENQUEUED, not merged \u2014 auto-merge will land it once required checks pass. Exiting ${PR_MERGE_ENQUEUED_EXIT_CODE} so a chained command does not treat this as a completed merge.`);
+        console.warn(`pr merge: exiting ${PR_MERGE_ENQUEUED_EXIT_CODE} so a chained command does not treat this as a completed merge.`);
         process.exitCode = PR_MERGE_ENQUEUED_EXIT_CODE;
       }
       return;
@@ -25025,6 +25326,7 @@ program2.parseAsync(process.argv).then(() => finishCliRun()).catch((e) => failGr
 0 && (module.exports = {
   DEFAULT_PRIORITY,
   awsCallerArn,
+  classifyParseError,
   gcPlan,
   isOrgRegisteredRepo,
   registryClientDeps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "3.38.0",
+  "version": "3.39.0",
   "description": "MMI Future CLI — the org dev toolbox (board, registry, keyless secrets, release train, bootstrap, doctor) and the cross-IDE engine the plugin's session-start hook drives.",
   "type": "module",
   "license": "UNLICENSED",