@mutmutco/cli 2.11.0 → 2.12.0

package/dist/index.cjs

@@ -3392,9 +3392,9 @@ function useColor() {
 var program = new Command();
 
 // src/index.ts
-var import_promises = require("node:fs/promises");
+var import_promises2 = require("node:fs/promises");
 var import_node_fs5 = require("node:fs");
-var import_node_crypto = require("node:crypto");
+var import_node_crypto2 = require("node:crypto");
 
 // src/rules-sync.ts
 function normalizeEol(s) {
@@ -3468,6 +3468,25 @@ async function runSessionStart(parallel, sequential, io) {
   for (const lines of buffered) flush(lines, io);
   for (const step of sequential) flush(await runBufferedStep(step), io);
 }
+function buildSessionStartPlan(verbs) {
+  return {
+    parallel: [
+      { name: "rules sync", run: verbs.rulesSync },
+      { name: "saga show", run: verbs.sagaShow },
+      { name: "saga health", run: verbs.sagaHealth }
+    ],
+    sequential: [{ name: "doctor", run: verbs.doctor }]
+  };
+}
+function spawnDetachedSelf(args, deps) {
+  try {
+    deps.spawn(deps.execPath, [deps.scriptPath, ...args], { detached: true, stdio: "ignore", windowsHide: true }).unref();
+  } catch {
+  }
+}
+function northstarPointer() {
+  return "North Stars: run `mmi-cli northstar relevant` to load plans relevant to your task (`northstar list` for all).";
+}
 
 // src/saga-capture.ts
 function parseHookInput(stdin) {
@@ -3482,8 +3501,8 @@ function parseHookInput(stdin) {
 // src/index.ts
 var import_node_child_process6 = require("node:child_process");
 var import_node_util6 = require("node:util");
-var import_node_path5 = require("node:path");
-var import_node_os = require("node:os");
+var import_node_path6 = require("node:path");
+var import_node_os2 = require("node:os");
 
 // src/saga-head-maintainer.ts
 var import_node_child_process2 = require("node:child_process");
@@ -3608,6 +3627,12 @@ async function runHeadEngine(prompt, timeoutMs = HEAD_ENGINE_TIMEOUT_MS) {
   });
 }
 
+// src/gh-create.ts
+var import_promises = require("node:fs/promises");
+var import_node_os = require("node:os");
+var import_node_path3 = require("node:path");
+var import_node_crypto = require("node:crypto");
+
 // src/board-priority.ts
 var BOARD_PRIORITY_NAMES = ["Urgent", "High", "Medium", "Low"];
 var CLI_PRIORITIES = ["urgent", "high", "medium", "low"];
@@ -3646,6 +3671,11 @@ function recoverPriorityFromEvents(events) {
 
 // src/gh-create.ts
 var ISSUE_TYPES = ["bug", "feature", "task"];
+var GH_MUTATION_TIMEOUT_MS = 12e4;
+function timeoutKillNote(err, timeoutMs) {
+  if (typeof err !== "object" || err === null || !err.killed) return void 0;
+  return `killed at the ${timeoutMs}ms timeout \u2014 the write may have completed server-side; verify before retrying`;
+}
 function normalizePriority(priority) {
   const p = priority.trim().toLowerCase();
   if (!CLI_PRIORITIES.includes(p)) {
@@ -3673,6 +3703,24 @@ function buildIssueArgs({ type, title, body, priority, repo, labels }) {
   for (const label of labels ?? []) args.push("--label", label);
   return args;
 }
+async function bodyArgsViaFile(args, deps = {}) {
+  const i = args.indexOf("--body");
+  if (i === -1 || i + 1 >= args.length) return { args, cleanup: async () => {
+  } };
+  const write = deps.write ?? import_promises.writeFile;
+  const remove = deps.remove ?? import_promises.unlink;
+  const file = (0, import_node_path3.join)(deps.dir ?? (0, import_node_os.tmpdir)(), `mmi-gh-body-${process.pid}-${(0, import_node_crypto.randomBytes)(4).toString("hex")}.md`);
+  await write(file, args[i + 1], "utf8");
+  return {
+    args: [...args.slice(0, i), "--body-file", file, ...args.slice(i + 2)],
+    cleanup: async () => {
+      try {
+        await remove(file);
+      } catch {
+      }
+    }
+  };
+}
 function buildAddToProjectArgs(projectId, contentId) {
   if (!projectId) throw new Error("addToProject: projectId is required");
   if (!contentId) throw new Error("addToProject: contentId is required");
@@ -3811,6 +3859,32 @@ function resumeCue() {
   return '> STATUS/RESUME CUE \u2014 For any status, resume, or "where do I stand" report: read THIS saga HEAD first (`mmi-cli saga show`), then reconcile its NEXT / LAST 5 / DECISIONS against the live board + git/gh before reporting. Do not rebuild the picture from board/issues/memory while skipping the HEAD. PRECEDENCE: the HEAD is prior-session belief and MAY BE SUPERSEDED \u2014 the current live user/master instruction WINS over any conflicting HEAD anchor, NEXT, or checklist; follow the live instruction and treat the stale HEAD item as superseded.';
 }
 
+// src/fetch-retry.ts
+async function fetchWithRetry(fetchImpl, url, init, opts = {}) {
+  const attempts = opts.attempts ?? 3;
+  const baseDelayMs = opts.baseDelayMs ?? 250;
+  const retryOn = opts.retryOn ?? ((res) => res.status >= 500);
+  const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    const isLast = i === attempts - 1;
+    const attemptInit = opts.timeoutMs ? { ...init, signal: AbortSignal.timeout(opts.timeoutMs) } : init;
+    try {
+      const res = await fetchImpl(url, attemptInit);
+      if (!isLast && retryOn(res)) {
+        await sleep(baseDelayMs * 2 ** i);
+        continue;
+      }
+      return res;
+    } catch (e) {
+      lastErr = e;
+      if (isLast) throw e;
+      await sleep(baseDelayMs * 2 ** i);
+    }
+  }
+  throw lastErr;
+}
+
 // src/saga-note.ts
 var AGENT_SURFACE_TOKENS = ["claude", "codex", "cursor", "gemini"];
 var ROUTE_LEVEL_403 = "saga API route-level 403 from GitHubAuthorizer cache/policy";
@@ -5401,12 +5475,12 @@ function buildInstalledPluginVersionCheck(input) {
 // src/stage-runner.ts
 var import_node_child_process5 = require("node:child_process");
 var import_node_fs3 = require("node:fs");
-var import_node_path3 = require("node:path");
+var import_node_path4 = require("node:path");
 var import_node_net = require("node:net");
 var import_node_util5 = require("node:util");
 var execFileP3 = (0, import_node_util5.promisify)(import_node_child_process5.execFile);
 function stageStatePath(cwd = process.cwd()) {
-  return (0, import_node_path3.join)(cwd, "tmp", "stage", "state.json");
+  return (0, import_node_path4.join)(cwd, "tmp", "stage", "state.json");
 }
 function validateStageConfig(config = {}, action) {
   const problems = [];
@@ -6476,16 +6550,21 @@ var PROJECTS_ENVELOPE_KEY = "projects";
 
 // src/registry-client.ts
 var DEFAULT_TIMEOUT_MS2 = 8e3;
+var RETRY_ATTEMPTS = 3;
+function retriedFetch(deps, url, init) {
+  return fetchWithRetry(deps.fetch ?? fetch, url, init, {
+    attempts: RETRY_ATTEMPTS,
+    timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2
+  });
+}
 async function fetchTrainAuthority(repo, 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 GitHub token (gh auth login)" };
-  const doFetch = deps.fetch ?? fetch;
   try {
-    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}/train-authority?repo=${encodeURIComponent(repo)}`, {
+    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}/train-authority?repo=${encodeURIComponent(repo)}`, {
       method: "GET",
-      headers: { Authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2)
+      headers: { Authorization: `Bearer ${token}` }
     });
     if (!res.ok) return { ok: false, error: `train-authority HTTP ${res.status}` };
     const body = await res.json();
@@ -6499,12 +6578,10 @@ async function fetchProjectsList(deps) {
   if (!deps.baseUrl) return null;
   const token = await deps.token();
   if (!token) return null;
-  const doFetch = deps.fetch ?? fetch;
   try {
-    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}${PROJECTS_LIST_PATH}`, {
+    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}${PROJECTS_LIST_PATH}`, {
       method: "GET",
-      headers: { Authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2)
+      headers: { Authorization: `Bearer ${token}` }
     });
     if (!res.ok) return null;
     const body = await res.json();
@@ -6523,12 +6600,10 @@ async function fetchProjectBySlugChecked(slug, deps) {
   if (!slug) return { ok: false, error: "no slug" };
   const token = await deps.token();
   if (!token) return { ok: false, error: "no GitHub token (run `gh auth login`)" };
-  const doFetch = deps.fetch ?? fetch;
   try {
-    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}/projects/${encodeURIComponent(slug)}`, {
+    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}/projects/${encodeURIComponent(slug)}`, {
       method: "GET",
-      headers: { Authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2)
+      headers: { Authorization: `Bearer ${token}` }
     });
     if (res.status === 404) return { ok: true, project: null };
     if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
@@ -6545,12 +6620,10 @@ async function fetchDeployStatusBySlug(slug, deps) {
   if (!deps.baseUrl || !slug) return null;
   const token = await deps.token();
   if (!token) return null;
-  const doFetch = deps.fetch ?? fetch;
   try {
-    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}/projects/${encodeURIComponent(slug)}/deploy-status`, {
+    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}/projects/${encodeURIComponent(slug)}/deploy-status`, {
       method: "GET",
-      headers: { Authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2)
+      headers: { Authorization: `Bearer ${token}` }
     });
     if (!res.ok) return null;
     const body = await res.json();
@@ -6564,12 +6637,10 @@ async function fetchOrgConfig(deps) {
   if (!deps.baseUrl) return null;
   const token = await deps.token();
   if (!token) return null;
-  const doFetch = deps.fetch ?? fetch;
   try {
-    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}${ORG_CONFIG_PATH}`, {
+    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}${ORG_CONFIG_PATH}`, {
       method: "GET",
-      headers: { Authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2)
+      headers: { Authorization: `Bearer ${token}` }
     });
     if (!res.ok) return null;
     return await res.json();
@@ -6581,13 +6652,11 @@ async function postJson(pathSuffix, payload, deps, method = "POST") {
   if (!deps.baseUrl) return { ok: false, status: 0, body: null, error: "no Hub API URL (set MMI_HUB_URL or use a current MMI CLI/plugin build)" };
   const token = await deps.token();
   if (!token) return { ok: false, status: 0, body: null, error: "no GitHub token (run `gh auth login`)" };
-  const doFetch = deps.fetch ?? fetch;
   try {
-    const res = await doFetch(`${deps.baseUrl.replace(/\/$/, "")}${pathSuffix}`, {
+    const res = await retriedFetch(deps, `${deps.baseUrl.replace(/\/$/, "")}${pathSuffix}`, {
       method,
       headers: { Authorization: `Bearer ${token}`, "content-type": "application/json" },
-      body: JSON.stringify(payload),
-      signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2)
+      body: JSON.stringify(payload)
     });
     let body = null;
     try {
@@ -6658,9 +6727,12 @@ function appAttestationOf(meta) {
 function attestedLine(att) {
   return `App-owned readiness attested by @${att.by} on ${att.at.slice(0, 10)} \u2014 the static checklist is cleared (the doctor reads no product repo files); re-run \`mmi-cli project attest\` after app-owned structural changes.`;
 }
+var CONTRACT_UNDECLARED_LINE = "No runtime secrets declared \u2014 declare requiredRuntimeSecrets (a per-stage name map) in the registry META, or attest the app needs none with an explicit empty stage map ({ dev: [], rc: [], main: [] }).";
 function appGapsFor(meta, model, slug, projectType) {
   const attested = appAttestationOf(meta);
-  if (attested) return [attestedLine(attested)];
+  const isTenantWeb = !(projectType === "content" || model === "content") && projectType !== "desktop-game" && !(projectType === "non-deployable" || model === "none") && model !== "hub-serverless" && model !== "serverless";
+  const contractUndeclared = isTenantWeb && Boolean(meta) && !hasRuntimeSecretContract(meta?.requiredRuntimeSecrets);
+  if (attested) return contractUndeclared ? [attestedLine(attested), CONTRACT_UNDECLARED_LINE] : [attestedLine(attested)];
   if (projectType === "content" || model === "content") return ["Content/KB repo: keep app-owned work to docs/content changes; release train does not apply."];
   if (projectType === "desktop-game") {
     return [
@@ -6692,8 +6764,8 @@ function appGapsFor(meta, model, slug, projectType) {
     "Make app config fail clearly for missing required env in prod/rc instead of relying on hidden defaults.",
     "Keep app-owned README.md and architecture.md aligned with v2 central deploy/secrets reality."
   ];
-  if (meta && !hasRuntimeSecretContract(meta.requiredRuntimeSecrets)) {
-    gaps.unshift("No runtime secrets declared \u2014 declare requiredRuntimeSecrets (a per-stage name map) in the registry META, or attest the app needs none with an explicit empty stage map ({ dev: [], rc: [], main: [] }).");
+  if (contractUndeclared) {
+    gaps.unshift(CONTRACT_UNDECLARED_LINE);
   }
   if (slug === "mmi-katip") {
     gaps.push("Katip-specific app plan: declare Google Workspace service-account requirements, use the service account numeric OAuth2 client ID for DWD, remove prod-hidden impersonation defaults, and make non-critical Google Workspace failures degrade instead of crash-looping.");
@@ -6773,7 +6845,29 @@ async function runV2Heal(repoOrSlug, opts, deps) {
 async function buildV2Doctor(repoOrSlug, deps) {
   const slug = slugOfRepo(repoOrSlug);
   const repo = repoFrom(repoOrSlug, slug);
-  const meta = await deps.getProject(slug);
+  const read = await deps.getProject(slug);
+  if (!read.ok) {
+    const degradedSecrets = {
+      dev: { required: [], present: [], missing: [] },
+      rc: { required: [], present: [], missing: [] },
+      main: { required: [], present: [], missing: [] }
+    };
+    const degradedStage = {
+      dev: { ok: false, required: false },
+      rc: { ok: false, required: false },
+      main: { ok: false, required: false }
+    };
+    return {
+      ok: false,
+      repo,
+      slug,
+      registryError: read.error,
+      hubOwned: { meta: { ok: false, missing: [] }, deployCoords: degradedStage, deployState: degradedStage, secrets: degradedSecrets },
+      autoHealAvailable: [],
+      appOwnedGaps: [`Hub registry read failed (${read.error}) \u2014 diagnosis degraded; nothing is known about META, coords, or gaps. Likely transient (cold start, network, or auth blip): retry \`mmi-cli project doctor\` shortly.`]
+    };
+  }
+  const meta = read.project;
   const projectType = resolveProjectType(meta, repo);
   const model = resolveDeployModel(meta, repo);
   const autoHeal = buildV2HealPatch(repo, meta);
@@ -6879,6 +6973,30 @@ ${section}`.trim();
 // src/project-set.ts
 var UNSET_KEYS = ["oauth", "requiredRuntimeSecrets", "edgeDomains", "requiredGcpApis", "publishRequired"];
 var UNSET_KEY_SET = new Set(UNSET_KEYS);
+var RUNTIME_SECRET_STAGES = ["dev", "rc", "main"];
+function parseRuntimeSecretsVar(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('project set: requiredRuntimeSecrets must be JSON, e.g. {"dev":["KEY"],"rc":["KEY"],"main":["KEY"]}');
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("project set: requiredRuntimeSecrets must be a stage map (a flat array is not box-loadable)");
+  }
+  const map = parsed;
+  const out = {};
+  for (const [stage2, names] of Object.entries(map)) {
+    if (!RUNTIME_SECRET_STAGES.includes(stage2)) {
+      throw new Error(`project set: requiredRuntimeSecrets stage "${stage2}" \u2014 expected only ${RUNTIME_SECRET_STAGES.join("/")}`);
+    }
+    if (!Array.isArray(names) || names.some((n) => typeof n !== "string" || !n.trim())) {
+      throw new Error(`project set: requiredRuntimeSecrets.${stage2} must be an array of non-empty secret names`);
+    }
+    out[stage2] = names;
+  }
+  return out;
+}
 function buildProjectSetPatch(input) {
   const patch = {};
   if (input.class) {
@@ -6908,6 +7026,8 @@ function buildProjectSetPatch(input) {
         const n = Number(raw);
         if (!Number.isFinite(n)) throw new Error("project set: projectNumber must be numeric");
         patch[key] = n;
+      } else if (key === "requiredRuntimeSecrets") {
+        patch[key] = parseRuntimeSecretsVar(raw);
       } else {
         patch[key] = raw;
       }
@@ -6967,10 +7087,91 @@ function parseKbTree(stdout, prefix) {
 }
 
 // src/plan.ts
-var import_node_path4 = require("node:path");
+var import_node_path5 = require("node:path");
+
+// src/frontmatter.ts
+function splitFrontmatter(content) {
+  const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(content);
+  if (!match) return { entries: [], body: content };
+  return { entries: match[1].split(/\r?\n/).filter((line) => line.trim()), body: content.slice(match[0].length) };
+}
+function entryKeyValue(line) {
+  const i = line.indexOf(":");
+  if (i < 0) return null;
+  return { key: line.slice(0, i).trim().toLowerCase(), value: line.slice(i + 1).trim() };
+}
+function frontmatterValue(content, key) {
+  const want = key.trim().toLowerCase();
+  for (const line of splitFrontmatter(content).entries) {
+    const kv = entryKeyValue(line);
+    if (kv && kv.key === want) return kv.value || void 0;
+  }
+  return void 0;
+}
+function frontmatterList(content, key) {
+  const raw = frontmatterValue(content, key);
+  if (!raw) return [];
+  return raw.replace(/^\[/, "").replace(/\]$/, "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+function extractPlanMeta(content) {
+  const meta = {};
+  const status = frontmatterValue(content, "status");
+  if (status) meta.status = status;
+  const tags = frontmatterList(content, "topic-tags");
+  if (tags.length) meta.topicTags = tags;
+  const title = frontmatterValue(content, "title");
+  if (title) meta.title = title;
+  const supersedes = frontmatterValue(content, "supersedes");
+  if (supersedes) meta.supersedes = supersedes;
+  return meta;
+}
+
+// src/plan-relevance.ts
+var STOP = /* @__PURE__ */ new Set(["the", "and", "for", "with", "plan", "issue", "fix", "feat", "add", "wip", "src", "tsx", "mjs"]);
+function tokenize(s) {
+  return (s ?? "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3 && !STOP.has(t));
+}
+var SUPPRESSED = /* @__PURE__ */ new Set(["superseded", "graduated"]);
+function signalTokens(s) {
+  const all = [
+    ...tokenize(s.branch),
+    ...tokenize(s.issueTitle),
+    ...(s.issueLabels ?? []).flatMap(tokenize),
+    ...(s.changedFiles ?? []).flatMap(tokenize)
+  ];
+  return new Set(all);
+}
+function rankPlansByRelevance(plans, signals, opts = {}) {
+  const wanted = signalTokens(signals);
+  const eligible = opts.includeAll ? plans : plans.filter((p) => !p.status || !SUPPRESSED.has(p.status.toLowerCase()));
+  const ranked = eligible.map((plan2) => {
+    const tagTokens = new Set((plan2.topicTags ?? []).flatMap(tokenize));
+    const titleTokens = new Set(tokenize(plan2.title));
+    const slugTokens = new Set(tokenize(plan2.slug));
+    const matched = /* @__PURE__ */ new Set();
+    let score = 0;
+    for (const t of wanted) {
+      if (tagTokens.has(t)) {
+        score += 3;
+        matched.add(t);
+      } else if (titleTokens.has(t)) {
+        score += 2;
+        matched.add(t);
+      } else if (slugTokens.has(t)) {
+        score += 1;
+        matched.add(t);
+      }
+    }
+    return { plan: plan2, score, matched: [...matched] };
+  });
+  ranked.sort((a, b) => b.score - a.score || (b.plan.updatedAt ?? "").localeCompare(a.plan.updatedAt ?? ""));
+  return ranked;
+}
+
+// src/plan.ts
 var PLANS_DIR = "plans";
-var META_FILE = (0, import_node_path4.join)(PLANS_DIR, ".plan-meta.json");
-var planPath = (slug) => (0, import_node_path4.join)(PLANS_DIR, `${slug}.md`);
+var META_FILE = (0, import_node_path5.join)(PLANS_DIR, ".plan-meta.json");
+var planPath = (slug) => (0, import_node_path5.join)(PLANS_DIR, `${slug}.md`);
 var metaKey = (project2, slug) => `${project2}/${slug}`;
 function parseMeta(raw) {
   if (!raw) return {};
@@ -6999,12 +7200,7 @@ function formatPlanList(plans) {
   return plans.map((p) => `${p.slug}  \xB7  ${p.updatedAt ?? "-"}  \xB7  ${p.project}`).join("\n");
 }
 var TIMEOUT_MS = 8e3;
-var GRADUATION_KEYS = /* @__PURE__ */ new Set(["northstar-graduation", "privacy", "merged-pr"]);
-function splitFrontmatter(content) {
-  const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(content);
-  if (!match) return { entries: [], body: content };
-  return { entries: match[1].split(/\r?\n/).filter((line) => line.trim()), body: content.slice(match[0].length) };
-}
+var GRADUATION_KEYS = /* @__PURE__ */ new Set(["northstar-graduation", "privacy", "merged-pr", "status"]);
 function markPlanGraduated(content, opts) {
   const { entries, body } = splitFrontmatter(normalizeEol(content));
   const preserved = entries.filter((line) => {
@@ -7014,6 +7210,7 @@ function markPlanGraduated(content, opts) {
   const next = [
     ...preserved,
     "northstar-graduation: built-and-merged",
+    "status: graduated",
     "privacy: org",
     `merged-pr: ${opts.mergedPr}`
   ];
@@ -7033,6 +7230,8 @@ async function planPush(deps, slug, opts = {}) {
   const meta = parseMeta(deps.readMetaRaw());
   const entry = meta[metaKey(project2, slug)];
   const body = { project: project2, slug, content };
+  const frontmatterMeta = extractPlanMeta(content);
+  if (Object.keys(frontmatterMeta).length) body.meta = frontmatterMeta;
   if (opts.force) body.force = true;
   else if (entry?.etag) body.baseEtag = entry.etag;
   const res = await deps.fetch(`${deps.apiUrl}/plan/put`, {
@@ -7086,35 +7285,59 @@ async function planPull(deps, slug, opts = {}) {
   deps.log(`pulled ${slug} \u2192 ${planPath(slug)}`);
   return true;
 }
+async function fetchPlanList(deps, project2) {
+  const qs = project2 ? `?${new URLSearchParams({ project: project2 }).toString()}` : "";
+  const res = await deps.fetch(`${deps.apiUrl}/plan/list${qs}`, {
+    method: "GET",
+    headers: await deps.headers(),
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const { plans } = await res.json();
+  return plans ?? [];
+}
 async function planList(deps, opts = {}) {
   const project2 = opts.project ?? (opts.quiet ? await deps.project() : void 0);
-  const qs = project2 ? `?${new URLSearchParams({ project: project2 }).toString()}` : "";
-  let res;
+  let plans;
   try {
-    res = await deps.fetch(`${deps.apiUrl}/plan/list${qs}`, {
-      method: "GET",
-      headers: await deps.headers(),
-      signal: AbortSignal.timeout(TIMEOUT_MS)
-    });
+    plans = await fetchPlanList(deps, project2);
   } catch (e) {
     if (!opts.quiet) deps.err(`plan list: ${e.message}`);
     return;
   }
-  if (!res.ok) {
-    if (!opts.quiet) deps.err(`plan list failed: HTTP ${res.status}`);
-    return;
-  }
-  const { plans } = await res.json();
-  if (opts.json) {
-    deps.log(JSON.stringify(plans));
-    return;
-  }
+  if (opts.json) return deps.log(JSON.stringify(plans));
   if (!plans.length) {
     if (!opts.quiet) deps.log("no plans");
     return;
   }
   deps.log(formatPlanList(plans));
 }
+function formatRelevant(ranked) {
+  return ranked.map((r) => {
+    const why = r.matched.length ? `matches ${r.matched.join(", ")}` : "recent";
+    return `${r.plan.slug}  \xB7  ${why}  \xB7  mmi-cli northstar pull ${r.plan.slug}`;
+  }).join("\n");
+}
+async function relevantPlans(deps, signals, opts = {}) {
+  const project2 = opts.project ?? await deps.project();
+  let plans;
+  try {
+    const scoped = await fetchPlanList(deps, project2);
+    const unprojected = project2 === "-" ? [] : await fetchPlanList(deps, "-").catch(() => []);
+    const seen = new Set(scoped.map((p) => `${p.project}/${p.slug}`));
+    plans = [...scoped, ...unprojected.filter((p) => !seen.has(`${p.project}/${p.slug}`))];
+  } catch (e) {
+    deps.err(`northstar relevant: ${e.message}`);
+    return;
+  }
+  if (!plans.length) return deps.log("no North Stars for this repo yet");
+  const ranked = rankPlansByRelevance(plans, signals, { includeAll: opts.includeAll });
+  const top = (opts.includeAll ? ranked : ranked.filter((r) => r.score > 0)).slice(0, opts.limit ?? 5);
+  if (!top.length) {
+    return deps.log(`no task-relevant North Stars among ${plans.length} for this repo \u2014 \`mmi-cli northstar relevant --all\` lists recent ones`);
+  }
+  deps.log(formatRelevant(top));
+}
 async function planDelete(deps, slug, opts = {}) {
   const project2 = opts.project ?? await deps.project();
   const res = await deps.fetch(`${deps.apiUrl}/plan/delete`, {
@@ -7571,7 +7794,7 @@ async function sagaHeaders(extra = {}) {
 async function loadConfig() {
   let file = {};
   try {
-    file = JSON.parse(await (0, import_promises.readFile)(".mmi/config.json", "utf8"));
+    file = JSON.parse(await (0, import_promises2.readFile)(".mmi/config.json", "utf8"));
   } catch {
     file = {};
   }
@@ -7579,12 +7802,16 @@ async function loadConfig() {
   return file;
 }
 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();
   if (!floor.sagaApiUrl) return stripMutableBoardConfig(floor);
-  const meta = await fetchProjectBySlug(await repoSlug(), registryClientDeps(floor));
-  discoveredConfig = meta ? boardConfigFromProject(meta, floor) : stripMutableBoardConfig(floor);
+  const read = await fetchProjectBySlugChecked(await repoSlug(), registryClientDeps(floor));
+  if (!read.ok) throw registryDegradeError(read.error);
+  discoveredConfig = read.project ? boardConfigFromProject(read.project, floor) : stripMutableBoardConfig(floor);
   return discoveredConfig;
 }
 async function loadConfigForRepo(targetRepo2) {
@@ -7592,9 +7819,10 @@ async function loadConfigForRepo(targetRepo2) {
   const cwdRepo = await resolveRepo();
   if (cwdRepo && targetRepo2.toLowerCase() === cwdRepo.toLowerCase()) return loadConfigOrDiscover();
   const floor = await loadConfig();
-  const meta = await fetchProjectBySlug(slugOf(targetRepo2), registryClientDeps(floor));
-  if (!meta) return stripMutableBoardConfig(floor);
-  return boardConfigFromProject(meta, floor);
+  const read = await fetchProjectBySlugChecked(slugOf(targetRepo2), registryClientDeps(floor));
+  if (!read.ok) throw registryDegradeError(read.error);
+  if (!read.project) return stripMutableBoardConfig(floor);
+  return boardConfigFromProject(read.project, floor);
 }
 function repoFromSelector(selector) {
   const trimmed = selector.trim();
@@ -7631,7 +7859,7 @@ function sessionDeps() {
     },
     writePersisted: (id) => persistSession(id),
     now: () => /* @__PURE__ */ new Date(),
-    rand: () => (0, import_node_crypto.randomBytes)(4).toString("hex")
+    rand: () => (0, import_node_crypto2.randomBytes)(4).toString("hex")
   };
 }
 var resolveSessionId = () => resolveSession(sessionDeps());
@@ -7654,16 +7882,11 @@ async function postCapture(capture, quiet = false) {
       if (!quiet) console.error("mmi-cli saga: Hub API URL not configured");
       return;
     }
-    const res = await fetch(`${cfg.sagaApiUrl}/saga/capture`, {
+    const res = await fetchWithRetry(fetch, `${cfg.sagaApiUrl}/saga/capture`, {
       method: "POST",
       headers: await sagaHeaders({ "content-type": "application/json" }),
-      body: JSON.stringify({ ...capture, ...await sagaKey(cfg) }),
-      // Capture latency is high + variable (server-side HEAD render); 8s dropped larger notes. Match the
-      // head-write timeout (20s) so a continuity note isn't lost to a slow/cold backend. No client retry:
-      // the capture isn't guaranteed idempotent, so a retry after a server-side-completed write could
-      // duplicate the note. Backend capture-latency root cause tracked in #255.
-      signal: AbortSignal.timeout(2e4)
-    });
+      body: JSON.stringify({ ...capture, ...await sagaKey(cfg) })
+    }, { attempts: 2, timeoutMs: 2e4, retryOn: () => false });
     let message = "";
     if (!res.ok) {
       try {
@@ -7764,11 +7987,11 @@ async function applyGcPlan(plan2, remote) {
 }
 function resolveVersion() {
   try {
-    const manifest = (0, import_node_path5.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
+    const manifest = (0, import_node_path6.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
     return JSON.parse((0, import_node_fs5.readFileSync)(manifest, "utf8")).version || "0.0.0";
   } catch {
     try {
-      const pkg = (0, import_node_path5.join)(__dirname, "..", "package.json");
+      const pkg = (0, import_node_path6.join)(__dirname, "..", "package.json");
       return JSON.parse((0, import_node_fs5.readFileSync)(pkg, "utf8")).version || "0.0.0";
     } catch {
       return "0.0.0";
@@ -7777,7 +8000,7 @@ function resolveVersion() {
 }
 function readRepoVersion() {
   try {
-    return JSON.parse((0, import_node_fs5.readFileSync)((0, import_node_path5.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
+    return JSON.parse((0, import_node_fs5.readFileSync)((0, import_node_path6.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
   } catch {
     return void 0;
   }
@@ -7874,11 +8097,11 @@ async function runRulesSync(opts, io = consoleIo) {
   for (const entry of fetched) {
     if ("error" in entry) continue;
     const { file, source } = entry;
-    const current = (0, import_node_fs5.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
+    const current = (0, import_node_fs5.existsSync)(file) ? await (0, import_promises2.readFile)(file, "utf8") : null;
     if (needsUpdate(source, current)) {
       const slash = file.lastIndexOf("/");
       if (slash > 0) (0, import_node_fs5.mkdirSync)(file.slice(0, slash), { recursive: true });
-      await (0, import_promises.writeFile)(file, normalizeEol(source), "utf8");
+      await (0, import_promises2.writeFile)(file, normalizeEol(source), "utf8");
       changed++;
       if (!opts.quiet) io.log(`mmi-cli rules: updated ${file}`);
     }
@@ -7903,9 +8126,9 @@ async function runDocsSync(opts, io = consoleIo) {
         return null;
       }
     },
-    localContent: async (f) => (0, import_node_fs5.existsSync)(f) ? await (0, import_promises.readFile)(f, "utf8") : null,
+    localContent: async (f) => (0, import_node_fs5.existsSync)(f) ? await (0, import_promises2.readFile)(f, "utf8") : null,
     writeDoc: async (f, c) => {
-      await (0, import_promises.writeFile)(f, c, "utf8");
+      await (0, import_promises2.writeFile)(f, c, "utf8");
     }
   });
   for (const f of result.updated) io.log(`mmi-cli docs: updated ${f} (from origin/${def})`);
@@ -7917,7 +8140,7 @@ docs.command("sync").option("--quiet", "stay silent unless something changed or
 var saga = program2.command("saga").description("per-session continuity");
 async function runNote(summary, o) {
   const [sha, key] = await Promise.all([gitOut(["rev-parse", "--short", "HEAD"]), sagaKey(await loadConfig())]);
-  const capture = buildNoteCapture(summary, o, (0, import_node_crypto.randomUUID)(), { sha: sha || void 0, branch: key.branch });
+  const capture = buildNoteCapture(summary, o, (0, import_node_crypto2.randomUUID)(), { sha: sha || void 0, branch: key.branch });
   await postCapture(capture);
 }
 saga.command("note <summary>").description("record a one-line structured note into your saga (the per-turn capture)").option("--next <text>", 'set "where I left off" (NEXT)').option("--decision <text>", "append a verbatim decision").option("--queue-add <text>", "add a worklist item").option("--queue-done <n>", "mark worklist item N done").option("--verified", "mark this claim as checked against source (state: verified, else asserted)").option("--diagnostic", "isolate a probe write (state: diagnostic, source: probe) \u2014 never resume/LAST 5").option("--supersedes <key>", "retire prior decisions matching an evidence key (pr:N | file:path)").option("--anchor <intent>", "set the sprint North-Star (write-protected; needs --anchor-force to change)").option("--anchor-force", "overwrite an existing anchor").action((summary, o) => runNote(summary, o));
@@ -7931,7 +8154,7 @@ async function runSagaShow(opts, io = consoleIo) {
   try {
     const key = await sagaKey(cfg);
     const qs = opts.latestAnywhere ? "scope=anywhere" : new URLSearchParams({ project: key.project, branch: key.branch }).toString();
-    const res = await fetch(`${cfg.sagaApiUrl}/saga/head?${qs}`, { headers: await sagaHeaders(), signal: AbortSignal.timeout(3e3) });
+    const res = await fetchWithRetry(fetch, `${cfg.sagaApiUrl}/saga/head?${qs}`, { headers: await sagaHeaders() }, { attempts: 2, timeoutMs: 3e3 });
     if (res.ok) {
       io.log(resumeCue());
       return io.log(await res.text());
@@ -7939,7 +8162,7 @@ async function runSagaShow(opts, io = consoleIo) {
     if (!opts.quiet) io.log(`saga show failed: HTTP ${res.status}`);
   } catch (e) {
     if (!opts.quiet) {
-      const reason = e.name === "TimeoutError" ? "backend unreachable (timed out after 3s)" : e.message;
+      const reason = e.name === "TimeoutError" ? "backend unreachable (timed out after 2 attempts)" : e.message;
       io.err(`saga show: ${reason} \u2014 continuing without saga; diagnose with \`mmi-cli saga health --json\``);
     }
   }
@@ -7948,7 +8171,7 @@ saga.command("show").option("--quiet", "no-op silently when unconfigured/unreach
 saga.command("capture").option("--quiet", "capture silently (for the Stop hook)").description("per-turn deterministic capture (Stop hook): turn boundary + current sha").action(async (opts) => {
   const hook = parseHookInput(await readStdin());
   if (hook.session_id) persistSession(hook.session_id);
-  await postCapture({ event: "stop", id: (0, import_node_crypto.randomUUID)(), source: "hook", sha: await gitOut(["rev-parse", "--short", "HEAD"]), surface: agentSurface() }, opts.quiet ?? false);
+  await postCapture({ event: "stop", id: (0, import_node_crypto2.randomUUID)(), source: "hook", sha: await gitOut(["rev-parse", "--short", "HEAD"]), surface: agentSurface() }, opts.quiet ?? false);
 });
 saga.command("session").option("--quiet", "silent (for the SessionStart hook)").description("persist the harness session id for this repo (SessionStart hook)").action(async () => {
   const hook = parseHookInput(await readStdin());
@@ -8000,7 +8223,7 @@ saga.command("key").option("--json", "machine-readable output").description("pri
 });
 async function probeBackend(url) {
   try {
-    const res = await fetch(`${url}/saga/head`, { headers: await sagaHeaders(), signal: AbortSignal.timeout(8e3) });
+    const res = await fetchWithRetry(fetch, `${url}/saga/head`, { headers: await sagaHeaders() }, { attempts: 3, timeoutMs: 4e3 });
     let message = "";
     try {
       const body = await res.clone().json();
@@ -8098,12 +8321,17 @@ kb.command("list [prefix]").description("list KB document paths (optionally unde
   }
 });
 async function ghCreate(args) {
+  const swapped = await bodyArgsViaFile(args);
   try {
-    const { stdout } = await execFileP4("gh", args);
+    const { stdout } = await execFileP4("gh", swapped.args, { timeout: GH_MUTATION_TIMEOUT_MS });
     return parseCreatedUrl(stdout);
   } catch (e) {
+    await swapped.cleanup();
     const err = e;
-    fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}`);
+    const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
+    fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}${note ? ` (${note})` : ""}`);
+  } finally {
+    await swapped.cleanup();
   }
 }
 async function ghJson(args, timeout = 1e4) {
@@ -8123,7 +8351,13 @@ async function resolveRepo(repo) {
 }
 async function attachToProject(issueNumber, repo, priority) {
   const targetRepo2 = await resolveRepo(repo);
-  const cfg = await loadConfigForRepo(targetRepo2);
+  let cfg;
+  try {
+    cfg = await loadConfigForRepo(targetRepo2);
+  } catch (e) {
+    console.error(`issue create: board attach skipped \u2014 ${e.message}`);
+    return void 0;
+  }
   if (!cfg.projectId) {
     console.error(`issue create: board attach skipped \u2014 no Hub registry board META for ${targetRepo2 ?? "current repo"}; run \`mmi-cli project get ${targetRepo2 ?? "<owner/repo>"}\` and backfill board coords`);
     return void 0;
@@ -8134,7 +8368,7 @@ async function attachToProject(issueNumber, repo, priority) {
     const { stdout: idOut } = await execFileP4("gh", viewArgs, { timeout: 1e4 });
     const contentId = idOut.trim();
     if (!contentId) throw new Error("could not resolve issue node id");
-    const { stdout } = await execFileP4("gh", buildAddToProjectArgs(cfg.projectId, contentId), { timeout: 1e4 });
+    const { stdout } = await execFileP4("gh", buildAddToProjectArgs(cfg.projectId, contentId), { timeout: GH_MUTATION_TIMEOUT_MS });
     const projectItemId = parseAddedItemId(stdout);
     if (projectItemId && priority) {
       try {
@@ -8226,6 +8460,26 @@ async function withPlan(quiet, run, io = consoleIo) {
   }
   await run(makePlanDeps(cfg, io));
 }
+async function gatherRelevanceSignals() {
+  const branch = await gitOut(["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "") || void 0;
+  const changed = (await gitOut(["diff", "--name-only", "HEAD"]).catch(() => "")).split("\n").map((s) => s.trim()).filter(Boolean);
+  const signals = { branch, changedFiles: changed.length ? changed : void 0 };
+  const issueNum = branch?.match(/\b(\d{2,})\b/)?.[1];
+  if (issueNum) {
+    try {
+      const { stdout } = await execFileP4(
+        "gh",
+        ["issue", "view", issueNum, "--json", "title,labels", "--jq", "{title:.title,labels:[.labels[].name]}"],
+        { timeout: 1e4 }
+      );
+      const j = JSON.parse(stdout);
+      if (j.title) signals.issueTitle = j.title;
+      if (j.labels?.length) signals.issueLabels = j.labels;
+    } catch {
+    }
+  }
+  return signals;
+}
 function registerNorthStarCommands(cmd) {
   cmd.command("push <slug>").description("push a local North Star plan (plans/<slug>.md) to the server").option("--project <name>", "override the project key").option("--force", "overwrite the remote even if it changed since your last sync").action((slug, o) => withPlan(false, async (d) => {
     const ok = await planPush(d, slug, o);
@@ -8236,6 +8490,10 @@ function registerNorthStarCommands(cmd) {
     if (!ok) process.exitCode = 1;
   }));
   cmd.command("list").description("list your North Star plans (cross-device)").option("--project <name>", "filter by project").option("--json", "machine-readable output").option("--quiet", "silent when unconfigured/empty/unreachable (SessionStart hook)").action((o) => withPlan(o.quiet ?? false, (d) => planList(d, o)));
+  cmd.command("relevant").description("list North Stars relevant to your current task (branch + claimed issue + changed files)").option("--project <name>", "override the project key").option("--all", "include superseded/graduated and recent non-matching plans").option("--limit <n>", "max results (default 5)").action((o) => withPlan(false, async (d) => {
+    const signals = await gatherRelevanceSignals();
+    await relevantPlans(d, signals, { project: o.project, includeAll: o.all, limit: o.limit ? Number(o.limit) : void 0 });
+  }));
   cmd.command("open <slug>").description("pull if needed, then open plans/<slug>.md in $EDITOR").option("--project <name>", "override the project key").action(
     (slug, o) => withPlan(false, async (d) => {
       const ok = await planPull(d, slug, { project: o.project });
@@ -8346,7 +8604,8 @@ tenant.command("control <owner/repo> <stage> <action>").description("run bounded
 async function v2ReadinessDeps(cfg) {
   const reg = registryClientDeps(cfg);
   return {
-    getProject: (slug) => fetchProjectBySlug(slug, reg),
+    // Checked read (#727/#733): the doctor distinguishes a FAILED read (degraded report) from a 404.
+    getProject: (slug) => fetchProjectBySlugChecked(slug, reg),
     hasDeployCoords: async (slug, stage2) => {
       const status = await fetchDeployStatusBySlug(slug, reg);
       return Boolean(status?.stages[stage2]);
@@ -8359,11 +8618,10 @@ async function v2ReadinessDeps(cfg) {
       const apiUrl = cfg.sagaApiUrl;
       if (!apiUrl) throw new Error("Hub API URL not configured \u2014 cannot verify secret names (set sagaApiUrl)");
       const qs = new URLSearchParams({ repo: targetRepo2 }).toString();
-      const res = await fetch(`${apiUrl.replace(/\/$/, "")}/secrets/list?${qs}`, {
+      const res = await fetchWithRetry(fetch, `${apiUrl.replace(/\/$/, "")}/secrets/list?${qs}`, {
         method: "GET",
-        headers: await sagaHeaders(),
-        signal: AbortSignal.timeout(8e3)
-      });
+        headers: await sagaHeaders()
+      }, { attempts: 2, timeoutMs: 5e3 });
       if (!res.ok) throw new Error(`secrets list failed for ${targetRepo2}: HTTP ${res.status}`);
       const body = await res.json();
       return (body.secrets ?? []).map((s) => s.key).filter(Boolean);
@@ -8377,15 +8635,25 @@ async function updateV2ReadinessIssue(repo, report, healed) {
   const issues = JSON.parse(list.stdout || "[]");
   const existing = issues.find((i) => i.title.toLowerCase().includes("v2 readiness"));
   if (!existing) {
-    const created = await execFileP4("gh", ["issue", "create", "--repo", repo, "--title", title, "--body", freshBody, "--label", "feature"], { timeout: 2e4 });
-    const url = created.stdout.trim();
-    const number = Number(url.match(/\/issues\/(\d+)$/)?.[1] ?? 0);
-    return { number, url, action: "created" };
+    const create = await bodyArgsViaFile(["issue", "create", "--repo", repo, "--title", title, "--body", freshBody, "--label", "feature"]);
+    try {
+      const created = await execFileP4("gh", create.args, { timeout: GH_MUTATION_TIMEOUT_MS });
+      const url = created.stdout.trim();
+      const number = Number(url.match(/\/issues\/(\d+)$/)?.[1] ?? 0);
+      return { number, url, action: "created" };
+    } finally {
+      await create.cleanup();
+    }
   }
   const view = await execFileP4("gh", ["issue", "view", String(existing.number), "--repo", repo, "--json", "body,url", "--jq", "{body:.body,url:.url}"], { timeout: 2e4 });
   const current = JSON.parse(view.stdout || "{}");
   const nextBody = renderReadinessIssueBody(current.body ?? "", report, { healed });
-  await execFileP4("gh", ["issue", "edit", String(existing.number), "--repo", repo, "--body", nextBody], { timeout: 2e4 });
+  const edit = await bodyArgsViaFile(["issue", "edit", String(existing.number), "--repo", repo, "--body", nextBody]);
+  try {
+    await execFileP4("gh", edit.args, { timeout: GH_MUTATION_TIMEOUT_MS });
+  } finally {
+    await edit.cleanup();
+  }
   return { number: existing.number, url: current.url ?? `https://github.com/${repo}/issues/${existing.number}`, action: "updated" };
 }
 var project = program2.command("project").description("the DDB org registry \u2014 list/get projects (any member); attest is project-admin; set is master-only");
@@ -8487,7 +8755,7 @@ project.command("attest [owner/repo]").description("attest this repo's app-owned
   const res = await attestAppGaps(slugOf(target), repo, registryClientDeps(cfg));
   reportWrite("project attest", res);
 });
-project.command("set [owner/repo]").description("MASTER-ONLY: upsert a project META (idempotent merge; defaults to the current repo; no clobber of unspecified fields)").option("--class <class>", "deployable | content").option("--project-type <type>", `${PROJECT_TYPES.join(" | ")} (v2 capability shape)`).option("--deploy-model <model>", `${DEPLOY_MODELS.join(" | ")} (release/deploy path; none means no Hub deploy registration)`).option("--var <KEY=VALUE...>", "META field to set (repeatable): name, division, projectId, branch, wikiRepo, vaultPath, kbPointer").option("--unset <KEY...>", "META field to remove (repeatable): oauth, requiredRuntimeSecrets, edgeDomains, requiredGcpApis, publishRequired").option("--clear-web-profile", "remove web-only registry fields (oauth, edgeDomains) for non-web/content projects").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
+project.command("set [owner/repo]").description("MASTER-ONLY: upsert a project META (idempotent merge; defaults to the current repo; no clobber of unspecified fields)").option("--class <class>", "deployable | content").option("--project-type <type>", `${PROJECT_TYPES.join(" | ")} (v2 capability shape)`).option("--deploy-model <model>", `${DEPLOY_MODELS.join(" | ")} (release/deploy path; none means no Hub deploy registration)`).option("--var <KEY=VALUE...>", 'META field to set (repeatable): name, division, projectId, branch, wikiRepo, vaultPath, kbPointer, requiredRuntimeSecrets (JSON stage map, e.g. {"dev":["KEY"],"rc":["KEY"],"main":["KEY"]})').option("--unset <KEY...>", "META field to remove (repeatable): oauth, requiredRuntimeSecrets, edgeDomains, requiredGcpApis, publishRequired").option("--clear-web-profile", "remove web-only registry fields (oauth, edgeDomains) for non-web/content projects").option("--json", "machine-readable output").action(async (repoOrSlug, o) => {
   const cfg = await loadConfig();
   let target;
   try {
@@ -8591,7 +8859,7 @@ issue.command("create").description("create an issue (type \u2192 label) and pri
   let priority;
   let body;
   try {
-    body = await resolveIssueBody({ body: o.body, bodyFile: o.bodyFile }, { readFile: import_promises.readFile, readStdin });
+    body = await resolveIssueBody({ body: o.body, bodyFile: o.bodyFile }, { readFile: import_promises2.readFile, readStdin });
     priority = normalizePriority(o.priority);
     args = buildIssueArgs({ type: o.type, title: o.title, body, priority, repo: o.repo, labels: o.label });
   } catch (e) {
@@ -8601,7 +8869,7 @@ issue.command("create").description("create an issue (type \u2192 label) and pri
     const la = ["label", "create", label, "--color", "ededed"];
     if (o.repo) la.push("--repo", o.repo);
     try {
-      await execFileP4("gh", la, { timeout: 1e4 });
+      await execFileP4("gh", la, { timeout: GH_MUTATION_TIMEOUT_MS });
     } catch {
     }
   }
@@ -8641,7 +8909,7 @@ issue.command("discover-related").description("find related issues for an existi
       "comments"
     ]);
     if (viewed.comments.some((comment) => comment.body.includes(relatedMarker(number)))) return;
-    await execFileP4("gh", ["issue", "comment", String(number), "--repo", repo, "--body", buildRelatedComment(number, candidates)], { timeout: 1e4 });
+    await execFileP4("gh", ["issue", "comment", String(number), "--repo", repo, "--body", buildRelatedComment(number, candidates)], { timeout: GH_MUTATION_TIMEOUT_MS });
   } catch {
   }
 });
@@ -8652,7 +8920,7 @@ program2.command("report").description("file a friction report on the Hub board
   const targetRepo2 = o.repo ?? HUB_REPO;
   const sourceRepo = await resolveRepo(void 0);
   try {
-    body = await resolveIssueBody({ body: o.body, bodyFile: o.bodyFile }, { readFile: import_promises.readFile, readStdin });
+    body = await resolveIssueBody({ body: o.body, bodyFile: o.bodyFile }, { readFile: import_promises2.readFile, readStdin });
     priority = normalizePriority(o.priority);
     args = buildIssueArgs({
       type: o.type,
@@ -8687,7 +8955,7 @@ program2.command("report").description("file a friction report on the Hub board
     const dup = findDuplicateReport({ title: o.title, body }, openReports);
     if (dup) {
       try {
-        await execFileP4("gh", ["issue", "comment", String(dup.number), "--repo", targetRepo2, "--body", buildDupComment(dup.number, body, sourceRepo)], { timeout: 1e4 });
+        await execFileP4("gh", ["issue", "comment", String(dup.number), "--repo", targetRepo2, "--body", buildDupComment(dup.number, body, sourceRepo)], { timeout: GH_MUTATION_TIMEOUT_MS });
       } catch (e) {
         const err = e;
         return fail(`report: duplicate of #${dup.number} (${dup.url}) but the +1 comment failed: ${(err.stderr || err.message || String(e)).trim()}`);
@@ -8696,7 +8964,7 @@ program2.command("report").description("file a friction report on the Hub board
     }
   }
   try {
-    await execFileP4("gh", ["label", "create", REPORT_LABEL, "--color", "ededed", "--repo", targetRepo2], { timeout: 1e4 });
+    await execFileP4("gh", ["label", "create", REPORT_LABEL, "--color", "ededed", "--repo", targetRepo2], { timeout: GH_MUTATION_TIMEOUT_MS });
   } catch {
   }
   const created = await ghCreate(args);
@@ -8704,8 +8972,14 @@ program2.command("report").description("file a friction report on the Hub board
   console.log(JSON.stringify({ ...created, deduped: false, label: REPORT_LABEL, priority, projectItemId }));
 });
 var pr = program2.command("pr").description("pull requests \u2014 reliable create with structured output");
-pr.command("create").description("create a PR and print {number,url} JSON").requiredOption("--title <title>", "PR title").requiredOption("--body <body>", "PR body (markdown)").option("--base <branch>", "base branch (defaults to the repo default)").option("--head <branch>", "head branch (defaults to the current branch)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(async (o) => {
-  const created = await ghCreate(buildPrArgs({ title: o.title, body: o.body, base: o.base, head: o.head, repo: o.repo }));
+pr.command("create").description("create a PR and print {number,url} JSON").requiredOption("--title <title>", "PR title").option("--body <body>", "PR body (markdown)").option("--body-file <path|->", "read PR body from a UTF-8 file, or from stdin with -").option("--base <branch>", "base branch (defaults to the repo default)").option("--head <branch>", "head branch (defaults to the current branch)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(async (o) => {
+  let body;
+  try {
+    body = await resolveIssueBody({ body: o.body, bodyFile: o.bodyFile }, { readFile: import_promises2.readFile, readStdin });
+  } catch (e) {
+    return fail(`pr create: ${e.message}`);
+  }
+  const created = await ghCreate(buildPrArgs({ title: o.title, body, base: o.base, head: o.head, repo: o.repo }));
   console.log(JSON.stringify(created));
 });
 async function remoteBranchExists(branch) {
@@ -8728,12 +9002,14 @@ pr.command("merge <number>").description("merge a PR (squash by default) and cle
   const remoteBefore = repoArgs.length ? void 0 : await remoteBranchExists(headRef);
   let remoteDeleteAttempted = false;
   let remoteNotAttemptedReason = repoArgs.length ? "repo-option" : void 0;
-  await execFileP4("gh", ["pr", "merge", number, ...repoArgs, method, "--delete-branch"], { timeout: GC_GH_TIMEOUT_MS }).catch((e) => {
+  await execFileP4("gh", ["pr", "merge", number, ...repoArgs, method, "--delete-branch"], { timeout: GH_MUTATION_TIMEOUT_MS }).catch((e) => {
     const message = String(e.message || "");
     if (/already been merged/i.test(message)) {
       remoteNotAttemptedReason = "pr-already-merged";
       return;
     }
+    const note = timeoutKillNote(e, GH_MUTATION_TIMEOUT_MS);
+    if (note) throw new Error(`gh pr merge ${number}: ${note}`);
     if (!/used by worktree|cannot delete branch/i.test(message)) throw e;
   });
   if (!remoteNotAttemptedReason) remoteDeleteAttempted = true;
@@ -8874,9 +9150,9 @@ function stageKeepAlive() {
   return setTimeout(() => void 0, 5 * 60 * 1e3);
 }
 program2.command("port-range <repo>").description("assign (idempotently) + print the repo's local stage port block via the atomic ORG#config.portCursor allocator (committed-file fallback)").option("--json", "machine-readable output").action(async (repo, o) => {
-  const path2 = (0, import_node_path5.join)(process.cwd(), "infra", "port-ranges.json");
+  const path2 = (0, import_node_path6.join)(process.cwd(), "infra", "port-ranges.json");
   const allocate = async (seed) => {
-    const { stdout } = await execFileP4("node", [(0, import_node_path5.join)(process.cwd(), "infra", "port-ddb.mjs"), String(seed)], { timeout: 15e3 });
+    const { stdout } = await execFileP4("node", [(0, import_node_path6.join)(process.cwd(), "infra", "port-ddb.mjs"), String(seed)], { timeout: 15e3 });
     const parsed = JSON.parse(stdout);
     if (!Array.isArray(parsed.range) || parsed.range.length !== 2) throw new Error("port-ddb: no range in output");
     return parsed.range;
@@ -9204,7 +9480,7 @@ access.command("audit").description("audit collaborator roles + train-branch pus
 var isWin = process.platform === "win32";
 var installedPluginsPath = (surface = detectSurface(process.env)) => {
   const homeDir = surface === "codex" ? ".codex" : ".claude";
-  return (0, import_node_path5.join)((0, import_node_os.homedir)(), homeDir, "plugins", "installed_plugins.json");
+  return (0, import_node_path6.join)((0, import_node_os2.homedir)(), homeDir, "plugins", "installed_plugins.json");
 };
 function readInstalledPlugins() {
   try {
@@ -9215,7 +9491,7 @@ function readInstalledPlugins() {
 }
 function readClaudeSettings() {
   try {
-    return JSON.parse((0, import_node_fs5.readFileSync)((0, import_node_path5.join)(process.cwd(), ".claude", "settings.json"), "utf8"));
+    return JSON.parse((0, import_node_fs5.readFileSync)((0, import_node_path6.join)(process.cwd(), ".claude", "settings.json"), "utf8"));
   } catch {
     return null;
   }
@@ -9261,14 +9537,14 @@ function backupAndWriteInstalledPlugins(records, pluginId) {
 }
 function mmiPluginCacheRootSnapshots() {
   const roots = [
-    { surface: "claude", root: (0, import_node_path5.join)((0, import_node_os.homedir)(), ".claude", "plugins", "cache", "mmi", "mmi") },
-    { surface: "codex", root: (0, import_node_path5.join)((0, import_node_os.homedir)(), ".codex", "plugins", "cache", "mmi", "mmi") }
+    { surface: "claude", root: (0, import_node_path6.join)((0, import_node_os2.homedir)(), ".claude", "plugins", "cache", "mmi", "mmi") },
+    { surface: "codex", root: (0, import_node_path6.join)((0, import_node_os2.homedir)(), ".codex", "plugins", "cache", "mmi", "mmi") }
   ];
   return roots.flatMap(({ surface, root }) => {
     try {
       const entries = (0, import_node_fs5.readdirSync)(root, { withFileTypes: true }).map((entry) => ({
         name: entry.name,
-        path: (0, import_node_path5.join)(root, entry.name),
+        path: (0, import_node_path6.join)(root, entry.name),
         isDirectory: entry.isDirectory()
       }));
       return [{ surface, root, entries }];
@@ -9291,7 +9567,7 @@ function quarantinePluginCacheDirs(plan2) {
     try {
       if (!(0, import_node_fs5.existsSync)(move.from)) continue;
       const target = uniqueQuarantineTarget(move.to);
-      (0, import_node_fs5.mkdirSync)((0, import_node_path5.dirname)(target), { recursive: true });
+      (0, import_node_fs5.mkdirSync)((0, import_node_path6.dirname)(target), { recursive: true });
       (0, import_node_fs5.renameSync)(move.from, target);
       moved += 1;
     } catch {
@@ -9299,7 +9575,7 @@ function quarantinePluginCacheDirs(plan2) {
   }
   return moved;
 }
-var gitignorePath = () => (0, import_node_path5.join)(process.cwd(), ".gitignore");
+var gitignorePath = () => (0, import_node_path6.join)(process.cwd(), ".gitignore");
 function readGitignore() {
   try {
     return (0, import_node_fs5.readFileSync)(gitignorePath(), "utf8");
@@ -9462,24 +9738,22 @@ async function runDoctor(opts, io = consoleIo) {
 ${gaps.length} item(s) need attention.` : "\nAll set \u2014 you are ready.");
 }
 program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, Hub API default, plugin git clone, plugin install record, .gitignore managed block, plugin config drift, installed plugin version) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--guide", "print the MMI Agentic Onboarding guide URL").option("--json", "machine-readable output").action((opts) => runDoctor(opts));
-program2.command("session-start").description("run the SessionStart verbs (rules/docs sync, saga session+show, plan list, saga health, doctor) in one process").action(async () => {
+program2.command("session-start").description("run the SessionStart verbs (rules sync, saga session+show, saga health, doctor) in one process; docs sync runs detached").action(async () => {
   try {
     const hook = parseHookInput(await readStdin());
     if (hook.session_id) persistSession(hook.session_id);
   } catch (e) {
     console.error(`[mmi-hook] saga session failed: ${e.message}`);
   }
-  const parallel = [
-    { name: "rules sync", run: (io) => runRulesSync({ quiet: true }, io) },
-    { name: "docs sync", run: (io) => runDocsSync({ quiet: true }, io) },
-    { name: "saga show", run: (io) => runSagaShow({ quiet: true }, io) },
-    { name: "plan list", run: (io) => withPlan(true, (d) => planList(d, { quiet: true }), io) },
-    { name: "saga health", run: (io) => runSagaHealth({ banner: true, quiet: true }, io) }
-  ];
-  const sequential = [
-    { name: "doctor", run: (io) => runDoctor({ banner: true }, io) }
-  ];
+  spawnDetachedSelf(["docs", "sync", "--quiet"], { spawn: import_node_child_process6.spawn, execPath: process.execPath, scriptPath: process.argv[1] });
+  const { parallel, sequential } = buildSessionStartPlan({
+    rulesSync: (io) => runRulesSync({ quiet: true }, io),
+    sagaShow: (io) => runSagaShow({ quiet: true }, io),
+    sagaHealth: (io) => runSagaHealth({ banner: true, quiet: true }, io),
+    doctor: (io) => runDoctor({ banner: true }, io)
+  });
   await runSessionStart(parallel, sequential, consoleIo);
+  consoleIo.log(northstarPointer());
 });
 function fail(msg) {
   console.error(`mmi-cli ${msg}`);

package/package.json

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