@mutmutco/cli 2.33.0 → 2.34.0

package/dist/main.cjs

@@ -4450,6 +4450,309 @@ function formatCaptureFailure(status, message) {
   return `saga: HTTP ${status}`;
 }
 
+// src/saga-snapshot.ts
+var GS_OPEN = "gs-open:";
+var GS_RESOLVED = "gs-resolved:";
+var GS_CEILING = "gs-ceiling:";
+var BS_DONE = "bs-done:";
+var BS_PROGRESS = "bs-progress:";
+var BS_BLOCKED = "bs-blocked:";
+var BS_TIER = "bs-tier:";
+var BS_CEILING = "bs-ceiling:";
+var BS_HALT = "bs-halt:";
+var GRIND_PREFIX = /^grind\s+/i;
+var META_ACTION_SEP = " | ";
+var LEGACY_BLOCKER_OPEN = /^blocker:(.+)$/i;
+var LEGACY_BLOCKER_RESOLVED = /^resolved:(.+)$/i;
+var LEGACY_CEILING = /^ceiling:(.+)$/i;
+var LEGACY_BUILD_DONE = /^done:(.+)$/i;
+var LEGACY_BUILD_PROGRESS = /^progress:(.+)$/i;
+var LEGACY_BUILD_BLOCKED = /^blocked:([^|]+)\|([^|]+)(?:\|(.+))?$/i;
+var LEGACY_BUILD_TIER = /^tier:([^|]+)\|([^|]+)(?:\|(.+))?$/i;
+var LEGACY_BUILD_CEILING = /^ceiling:([^|]+)\|(.+)$/i;
+var LEGACY_BUILD_HALT = /^halt:(.+)$/i;
+function isGrindSnapshotItem(text) {
+  return text.startsWith(GS_OPEN) || text.startsWith(GS_RESOLVED) || text.startsWith(GS_CEILING) || LEGACY_BLOCKER_OPEN.test(text) || LEGACY_BLOCKER_RESOLVED.test(text) || LEGACY_CEILING.test(text);
+}
+function isBuildSnapshotItem(text) {
+  return text.startsWith(BS_DONE) || text.startsWith(BS_PROGRESS) || text.startsWith(BS_BLOCKED) || text.startsWith(BS_TIER) || text.startsWith(BS_CEILING) || text.startsWith(BS_HALT) || LEGACY_BUILD_DONE.test(text) || LEGACY_BUILD_PROGRESS.test(text) || LEGACY_BUILD_BLOCKED.test(text) || LEGACY_BUILD_TIER.test(text) || LEGACY_BUILD_CEILING.test(text) || LEGACY_BUILD_HALT.test(text);
+}
+function snapshotClearIndices(kind, head) {
+  const pred = kind === "grind" ? isGrindSnapshotItem : isBuildSnapshotItem;
+  return (head.queued ?? []).map((item, index) => ({ item, index })).filter(({ item }) => !item.done && pred(item.text)).map(({ index }) => index);
+}
+function parseGrindNext(next) {
+  if (!next?.trim()) return {};
+  const raw = next.replace(GRIND_PREFIX, "").trim();
+  const pipe = raw.indexOf(META_ACTION_SEP);
+  const meta = pipe >= 0 ? raw.slice(0, pipe).trim() : raw;
+  const nextAction = pipe >= 0 ? raw.slice(pipe + META_ACTION_SEP.length).trim() : void 0;
+  const out = { nextAction };
+  for (const part of meta.split(/\s+/)) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const k = part.slice(0, eq);
+    const v = part.slice(eq + 1);
+    if (k === "class") out.class = v;
+    else if (k === "routing") out.routing = v;
+    else if (k === "ultra") out.ultra = v;
+    else if (k === "phase") out.phase = v;
+    else if (k === "verify") {
+      const [r, c] = v.split("/");
+      const rn = Number(r);
+      const cn = Number(c);
+      if (Number.isFinite(rn)) out.verifyRound = rn;
+      if (Number.isFinite(cn)) out.verifyCap = cn;
+    } else if (k === "resolved" && v) {
+      out.resolvedBlockerIds = v.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+  }
+  return out;
+}
+function formatGrindNext(s) {
+  const parts = ["grind"];
+  if (s.class) parts.push(`class=${s.class}`);
+  if (s.routing) parts.push(`routing=${s.routing}`);
+  if (s.ultra) parts.push(`ultra=${s.ultra}`);
+  if (s.phase) parts.push(`phase=${s.phase}`);
+  if (Number.isFinite(s.verifyRound) && Number.isFinite(s.verifyCap)) parts.push(`verify=${s.verifyRound}/${s.verifyCap}`);
+  if (s.resolvedBlockerIds.length) parts.push(`resolved=${s.resolvedBlockerIds.join(",")}`);
+  const meta = parts.join(" ");
+  return s.nextAction ? `${meta}${META_ACTION_SEP}${s.nextAction}` : meta;
+}
+function parseGrindQueueItem(item, open, resolved, ceiling) {
+  if (item.text.startsWith(GS_OPEN) && !item.done) open.push(item.text.slice(GS_OPEN.length).trim());
+  else if (item.text.startsWith(GS_RESOLVED) && !item.done) resolved.push(item.text.slice(GS_RESOLVED.length).trim());
+  else if (item.text.startsWith(GS_CEILING) && !item.done) ceiling.value = item.text.slice(GS_CEILING.length).trim();
+  else {
+    const legacyOpen = item.text.match(LEGACY_BLOCKER_OPEN);
+    if (legacyOpen && !item.done) open.push(legacyOpen[1].trim());
+    const legacyResolved = item.text.match(LEGACY_BLOCKER_RESOLVED);
+    if (legacyResolved && item.done) resolved.push(legacyResolved[1].trim());
+    const legacyCeil = item.text.match(LEGACY_CEILING);
+    if (legacyCeil && !item.done) ceiling.value = legacyCeil[1].trim();
+  }
+}
+function parseGrindSnapshot(head) {
+  const fromNext = parseGrindNext(head.next);
+  const openBlockerIds = [];
+  const resolvedFromQueue = [];
+  const ceiling = { value: void 0 };
+  for (const item of head.queued ?? []) {
+    parseGrindQueueItem(item, openBlockerIds, resolvedFromQueue, ceiling);
+  }
+  const resolvedBlockerIds = [.../* @__PURE__ */ new Set([...resolvedFromQueue, ...fromNext.resolvedBlockerIds ?? []])];
+  const { resolvedBlockerIds: _drop, ...restNext } = fromNext;
+  return {
+    kind: "grind",
+    criteria: head.anchor?.intent,
+    openBlockerIds,
+    resolvedBlockerIds,
+    verificationCeiling: ceiling.value,
+    ...restNext
+  };
+}
+function parseBuildSnapshot(head) {
+  const doneLastTurn = [];
+  const inProgress = [];
+  const blocked = [];
+  const tierLedger = [];
+  const verificationCeiling = [];
+  let haltReason;
+  for (const item of head.queued ?? []) {
+    if (item.text.startsWith(BS_DONE) && !item.done) {
+      doneLastTurn.push(item.text.slice(BS_DONE.length).trim());
+      continue;
+    }
+    if (item.text.startsWith(BS_PROGRESS) && !item.done) {
+      inProgress.push(item.text.slice(BS_PROGRESS.length).trim());
+      continue;
+    }
+    if (item.text.startsWith(BS_BLOCKED) && !item.done) {
+      const body = item.text.slice(BS_BLOCKED.length);
+      const [site, decision, issue2] = body.split("|");
+      blocked.push({ site: site?.trim() ?? "", decision: decision?.trim() ?? "", issue: issue2?.trim() });
+      continue;
+    }
+    if (item.text.startsWith(BS_TIER) && !item.done) {
+      const body = item.text.slice(BS_TIER.length);
+      const [site, tier2, signals] = body.split("|");
+      tierLedger.push({ site: site?.trim() ?? "", tier: tier2?.trim() ?? "", signals: signals?.trim() });
+      continue;
+    }
+    if (item.text.startsWith(BS_CEILING) && !item.done) {
+      const body = item.text.slice(BS_CEILING.length);
+      const [site, rung] = body.split("|");
+      verificationCeiling.push({ site: site?.trim() ?? "", rung: rung?.trim() ?? "" });
+      continue;
+    }
+    if (item.text.startsWith(BS_HALT) && !item.done) {
+      haltReason = item.text.slice(BS_HALT.length).trim();
+      continue;
+    }
+    if (item.done) {
+      const d = item.text.match(LEGACY_BUILD_DONE);
+      if (d) doneLastTurn.push(d[1].trim());
+      continue;
+    }
+    const prog = item.text.match(LEGACY_BUILD_PROGRESS);
+    if (prog) {
+      inProgress.push(prog[1].trim());
+      continue;
+    }
+    const blk = item.text.match(LEGACY_BUILD_BLOCKED);
+    if (blk) {
+      blocked.push({ site: blk[1].trim(), decision: blk[2].trim(), issue: blk[3]?.trim() });
+      continue;
+    }
+    const tier = item.text.match(LEGACY_BUILD_TIER);
+    if (tier) {
+      tierLedger.push({ site: tier[1].trim(), tier: tier[2].trim(), signals: tier[3]?.trim() });
+      continue;
+    }
+    const ceil = item.text.match(LEGACY_BUILD_CEILING);
+    if (ceil) {
+      verificationCeiling.push({ site: ceil[1].trim(), rung: ceil[2].trim() });
+      continue;
+    }
+    const halt = item.text.match(LEGACY_BUILD_HALT);
+    if (halt) haltReason = halt[1].trim();
+  }
+  const nextFrontier = [];
+  if (head.next?.trim()) {
+    for (const line of head.next.split(";").map((s) => s.trim()).filter(Boolean)) {
+      nextFrontier.push(line);
+    }
+  }
+  return {
+    kind: "build",
+    milestone: head.anchor?.intent,
+    northStarSlug: head.anchor?.slug,
+    doneLastTurn,
+    inProgress,
+    blocked,
+    nextFrontier,
+    tierLedger,
+    verificationCeiling,
+    haltReason
+  };
+}
+function parseSnapshot(kind, head) {
+  return kind === "grind" ? parseGrindSnapshot(head) : parseBuildSnapshot(head);
+}
+function strOrU(v) {
+  return typeof v === "string" && v.length ? v : void 0;
+}
+function numOrU(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function normalizeSnapshot(kind, raw) {
+  if (!raw || typeof raw !== "object") throw new Error("snapshot JSON must be an object");
+  const o = raw;
+  if (o.kind !== kind) throw new Error(`snapshot kind ${JSON.stringify(o.kind)} does not match --kind ${kind}`);
+  if (kind === "grind") {
+    return {
+      kind: "grind",
+      class: strOrU(o.class),
+      routing: strOrU(o.routing),
+      ultra: strOrU(o.ultra),
+      criteria: strOrU(o.criteria),
+      phase: strOrU(o.phase),
+      verifyRound: numOrU(o.verifyRound),
+      verifyCap: numOrU(o.verifyCap),
+      openBlockerIds: asStringArray(o.openBlockerIds),
+      resolvedBlockerIds: asStringArray(o.resolvedBlockerIds),
+      verificationCeiling: strOrU(o.verificationCeiling),
+      nextAction: strOrU(o.nextAction)
+    };
+  }
+  const blocked = Array.isArray(o.blocked) ? o.blocked.filter((b) => !!b && typeof b === "object").map((b) => ({ site: strOrU(b.site) ?? "", decision: strOrU(b.decision) ?? "", issue: strOrU(b.issue) })) : [];
+  const tierLedger = Array.isArray(o.tierLedger) ? o.tierLedger.filter((t) => !!t && typeof t === "object").map((t) => ({ site: strOrU(t.site) ?? "", tier: strOrU(t.tier) ?? "", signals: strOrU(t.signals) })) : [];
+  const verificationCeiling = Array.isArray(o.verificationCeiling) ? o.verificationCeiling.filter((v) => !!v && typeof v === "object").map((v) => ({ site: strOrU(v.site) ?? "", rung: strOrU(v.rung) ?? "" })) : [];
+  return {
+    kind: "build",
+    milestone: strOrU(o.milestone),
+    northStarSlug: strOrU(o.northStarSlug),
+    doneLastTurn: asStringArray(o.doneLastTurn),
+    inProgress: asStringArray(o.inProgress),
+    blocked,
+    nextFrontier: asStringArray(o.nextFrontier),
+    tierLedger,
+    verificationCeiling,
+    haltReason: strOrU(o.haltReason)
+  };
+}
+function planGrindSnapshotWrite(s, summary = "grind snapshot refresh") {
+  const queueOps = [];
+  for (const id of s.openBlockerIds) queueOps.push({ text: `${GS_OPEN}${id}` });
+  for (const id of s.resolvedBlockerIds) queueOps.push({ text: `${GS_RESOLVED}${id}` });
+  if (s.verificationCeiling) queueOps.push({ text: `${GS_CEILING}${s.verificationCeiling}` });
+  return {
+    summary,
+    next: formatGrindNext(s),
+    anchor: s.criteria,
+    queueOps,
+    clearIndices: []
+  };
+}
+function planBuildSnapshotWrite(s, summary = "build snapshot refresh") {
+  const queueOps = [];
+  for (const site of s.doneLastTurn) queueOps.push({ text: `${BS_DONE}${site}` });
+  for (const site of s.inProgress) queueOps.push({ text: `${BS_PROGRESS}${site}` });
+  for (const b of s.blocked) {
+    queueOps.push({ text: `${BS_BLOCKED}${b.site}|${b.decision}${b.issue ? `|${b.issue}` : ""}` });
+  }
+  for (const t of s.tierLedger) {
+    queueOps.push({ text: `${BS_TIER}${t.site}|${t.tier}${t.signals ? `|${t.signals}` : ""}` });
+  }
+  for (const v of s.verificationCeiling) queueOps.push({ text: `${BS_CEILING}${v.site}|${v.rung}` });
+  if (s.haltReason) queueOps.push({ text: `${BS_HALT}${s.haltReason}` });
+  return {
+    summary,
+    next: s.nextFrontier.length ? s.nextFrontier.join("; ") : void 0,
+    anchor: s.milestone,
+    anchorSlug: s.northStarSlug,
+    queueOps,
+    clearIndices: []
+  };
+}
+function planSnapshotWrite(snapshot, head, summary) {
+  const plan2 = snapshot.kind === "grind" ? planGrindSnapshotWrite(snapshot, summary) : planBuildSnapshotWrite(snapshot, summary);
+  plan2.clearIndices = snapshotClearIndices(snapshot.kind, head);
+  return plan2;
+}
+function formatSnapshotHuman(snapshot) {
+  if (snapshot.kind === "grind") {
+    const lines2 = [
+      `kind: grind`,
+      snapshot.class ? `class: ${snapshot.class}` : "",
+      snapshot.routing ? `routing: ${snapshot.routing}` : "",
+      snapshot.ultra ? `ultra: ${snapshot.ultra}` : "",
+      snapshot.criteria ? `criteria: ${snapshot.criteria}` : "",
+      snapshot.phase ? `phase: ${snapshot.phase}` : "",
+      snapshot.verifyRound != null ? `verify: ${snapshot.verifyRound}/${snapshot.verifyCap ?? "?"}` : "",
+      snapshot.openBlockerIds.length ? `open blockers: ${snapshot.openBlockerIds.join(", ")}` : "open blockers: (none)",
+      snapshot.resolvedBlockerIds.length ? `resolved: ${snapshot.resolvedBlockerIds.join(", ")}` : "",
+      snapshot.verificationCeiling ? `ceiling: ${snapshot.verificationCeiling}` : "",
+      snapshot.nextAction ? `next: ${snapshot.nextAction}` : ""
+    ].filter(Boolean);
+    return lines2.join("\n");
+  }
+  const lines = [
+    `kind: build`,
+    snapshot.milestone ? `milestone: ${snapshot.milestone}` : "",
+    snapshot.northStarSlug ? `north star: ${snapshot.northStarSlug}` : "",
+    snapshot.doneLastTurn.length ? `done: ${snapshot.doneLastTurn.join(", ")}` : "",
+    snapshot.inProgress.length ? `in progress: ${snapshot.inProgress.join(", ")}` : "",
+    snapshot.nextFrontier.length ? `next frontier: ${snapshot.nextFrontier.join("; ")}` : "",
+    snapshot.haltReason ? `halt: ${snapshot.haltReason}` : ""
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+
 // src/saga-commands.ts
 async function runNote(summary, o) {
   const [sha, key] = await Promise.all([gitOut(["rev-parse", "--short", "HEAD"]), sagaKey(await loadConfig())]);
@@ -4582,6 +4885,60 @@ async function runSagaHealth(o, io = consoleIo) {
   if (report.warnings.length) io.log(report.warnings.map((w) => ` - ${w}`).join("\n"));
   if (report.pendingNotes > 0) io.log(` - ${report.pendingNotes} note(s) queued locally \u2014 \`mmi-cli saga flush\` to roll forward`);
 }
+async function fetchSagaHead(io = consoleIo) {
+  const cfg = await loadConfig();
+  if (!cfg.sagaApiUrl) {
+    io.err("saga snapshot: Hub API URL not configured");
+    return null;
+  }
+  try {
+    const key = await sagaKey(cfg);
+    const qs = new URLSearchParams(key).toString();
+    const res = await fetch(`${cfg.sagaApiUrl}/saga/state?${qs}`, { headers: await hubHeaders(), signal: AbortSignal.timeout(8e3) });
+    if (!res.ok) {
+      io.err(`saga snapshot: HTTP ${res.status}`);
+      return null;
+    }
+    const state = await res.json();
+    return state.head ?? {};
+  } catch (e) {
+    io.err(`saga snapshot: ${e.message}`);
+    return null;
+  }
+}
+async function postSnapshotNotes(plan2, anchorForce) {
+  const [sha, key] = await Promise.all([gitOut(["rev-parse", "--short", "HEAD"]), sagaKey(await loadConfig())]);
+  const evidence = { sha: sha || void 0, branch: key.branch };
+  for (const idx of [...plan2.clearIndices].sort((a, b) => b - a)) {
+    const cap = buildNoteCapture("snapshot retire", { queueDone: String(idx) }, (0, import_node_crypto3.randomUUID)(), evidence);
+    await postCapture(cap);
+  }
+  const primary = buildNoteCapture(plan2.summary, {
+    next: plan2.next,
+    anchor: plan2.anchor,
+    anchorSlug: plan2.anchorSlug,
+    anchorForce
+  }, (0, import_node_crypto3.randomUUID)(), evidence);
+  await postCapture(primary);
+  for (const op of plan2.queueOps) {
+    const cap = buildNoteCapture("snapshot checklist", { queueAdd: op.text }, (0, import_node_crypto3.randomUUID)(), evidence);
+    await postCapture(cap);
+  }
+}
+async function runSagaSnapshotShow(opts, io = consoleIo) {
+  const head = await fetchSagaHead(io);
+  if (!head) return;
+  const snapshot = parseSnapshot(opts.kind, head);
+  if (opts.json) return io.log(JSON.stringify(snapshot, null, 2));
+  io.log(formatSnapshotHuman(snapshot));
+}
+async function runSagaSnapshotSet(snapshot, opts = {}, io = consoleIo) {
+  const head = await fetchSagaHead(io) ?? { queued: [] };
+  const plan2 = planSnapshotWrite(snapshot, head);
+  await postSnapshotNotes(plan2, opts.anchorForce);
+  if (opts.json) return io.log(JSON.stringify({ ok: true, snapshot, retired: plan2.clearIndices.length, queued: plan2.queueOps.length + 1 }));
+  io.log(`saga snapshot: wrote ${snapshot.kind} snapshot (retired ${plan2.clearIndices.length}, ${plan2.queueOps.length + 1} capture(s))`);
+}
 function registerSagaCommands(program3) {
   const saga = program3.command("saga").description("per-session continuity");
   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-slug <slug>", "bind the anchor to a North Star plan slug (SSOT at plans/.../<slug>.md)").option("--anchor-force", "overwrite an existing anchor").option("--message-file <path|->", "read the summary from a UTF-8 file, or from stdin with - (avoids cmd.exe quoting)").action(async (summary, o) => {
@@ -4647,6 +5004,69 @@ function registerSagaCommands(program3) {
     console.log(`project=${key.project} branch=${key.branch} session=${key.sessionId} source=${source}`);
   });
   saga.command("health").option("--json", "machine-readable output").option("--banner", "one-line SessionStart banner; silent when healthy").option("--quiet", "suppress detail output").description("zero-write health check: auth, backend reachability, resolved key").action((o) => runSagaHealth(o));
+  const snapshot = saga.command("snapshot").description("structured grind/build resume snapshot over saga HEAD");
+  snapshot.command("show").description("read the structured resume snapshot from current saga HEAD").requiredOption("--kind <kind>", "grind | build").option("--json", "output JSON").action(async (o) => {
+    const kind = o.kind;
+    if (kind !== "grind" && kind !== "build") return fail("saga snapshot show: --kind must be grind or build");
+    await runSagaSnapshotShow({ kind, json: o.json });
+  });
+  snapshot.command("set").description("write a structured resume snapshot (maps to saga note HEAD primitives)").requiredOption("--kind <kind>", "grind | build").option("--json-file <path>", "full snapshot JSON (overrides field flags)").option("--anchor-force", "overwrite an existing anchor").option("--json", "output result JSON").option("--class <c>", "grind class").option("--routing <r>", "grind routing tier").option("--ultra <u>", "ultra mode").option("--criteria <text>", "grind criteria / frame").option("--phase <p>", "phase reached").option("--verify-round <n>", "verify round", (v) => parseInt(v, 10)).option("--verify-cap <n>", "verify cap", (v) => parseInt(v, 10)).option("--open-blocker <id>", "open blocker id (repeatable)", (v, prev) => [...prev, v], []).option("--resolved-blocker <id>", "resolved blocker id (repeatable)", (v, prev) => [...prev, v], []).option("--verification-ceiling <text>", "verification ceiling").option("--next-action <text>", "next action").option("--milestone <text>", "build milestone one-liner").option("--north-star-slug <slug>", "North Star slug").option("--done <site>", "done last turn site (repeatable)", (v, prev) => [...prev, v], []).option("--in-progress <site>", "in-progress site (repeatable)", (v, prev) => [...prev, v], []).option("--blocked <spec>", "site|decision|issue (repeatable)", (v, prev) => [...prev, v], []).option("--next-frontier <item>", "frontier item (repeatable)", (v, prev) => [...prev, v], []).option("--tier <spec>", "site|tier|signals (repeatable)", (v, prev) => [...prev, v], []).option("--site-ceiling <spec>", "site|rung (repeatable)", (v, prev) => [...prev, v], []).option("--halt-reason <text>", "halt reason").action(async (o) => {
+    const kind = o.kind;
+    if (kind !== "grind" && kind !== "build") return fail("saga snapshot set: --kind must be grind or build");
+    let snap;
+    if (o.jsonFile) {
+      const raw = await (0, import_promises2.readFile)(o.jsonFile, "utf8");
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (e) {
+        return fail(`saga snapshot set: invalid JSON in ${o.jsonFile}: ${e.message}`);
+      }
+      try {
+        snap = normalizeSnapshot(kind, parsed);
+      } catch (e) {
+        return fail(`saga snapshot set: ${e.message}`);
+      }
+    } else if (kind === "grind") {
+      snap = {
+        kind: "grind",
+        class: o.class,
+        routing: o.routing,
+        ultra: o.ultra,
+        criteria: o.criteria,
+        phase: o.phase,
+        verifyRound: o.verifyRound,
+        verifyCap: o.verifyCap,
+        openBlockerIds: o.openBlocker ?? [],
+        resolvedBlockerIds: o.resolvedBlocker ?? [],
+        verificationCeiling: o.verificationCeiling,
+        nextAction: o.nextAction
+      };
+    } else {
+      snap = {
+        kind: "build",
+        milestone: o.milestone,
+        northStarSlug: o.northStarSlug,
+        doneLastTurn: o.done ?? [],
+        inProgress: o.inProgress ?? [],
+        blocked: (o.blocked ?? []).map((spec) => {
+          const [site, decision, issue2] = spec.split("|");
+          return { site: site ?? "", decision: decision ?? "", issue: issue2 };
+        }),
+        nextFrontier: o.nextFrontier ?? [],
+        tierLedger: (o.tier ?? []).map((spec) => {
+          const [site, tier, signals] = spec.split("|");
+          return { site: site ?? "", tier: tier ?? "", signals };
+        }),
+        verificationCeiling: (o.siteCeiling ?? []).map((spec) => {
+          const [site, rung] = spec.split("|");
+          return { site: site ?? "", rung: rung ?? "" };
+        }),
+        haltReason: o.haltReason
+      };
+    }
+    await runSagaSnapshotSet(snap, { anchorForce: o.anchorForce, json: o.json });
+  });
 }
 
 // src/honcho-commands.ts
@@ -7442,6 +7862,87 @@ function pickEffortTier(signals) {
   }
   return { tier: "standard", reason: "default \u2014 normal slice", budgets: getTierBudgets("standard") };
 }
+var VERIFICATION_DEPTH_ROUNDS = {
+  "panel-once": 1,
+  "full-panel": 2,
+  "full-double-pass": 4,
+  "integration-checkpoints": 6
+};
+var TIER_LADDER = ["light", "standard", "deep", "max"];
+var CAMPAIGN_ITERATION_CAP = 15;
+var COST_CEILING = 500;
+function estimateWorstCaseCost(input) {
+  const tier = input.tier ?? (input.signals ? pickEffortTier(input.signals).tier : "standard");
+  const budgets = getTierBudgets(tier);
+  const verifyRounds = VERIFICATION_DEPTH_ROUNDS[budgets.verificationDepth];
+  const sites = Math.max(1, input.plannedSiteCount ?? 1);
+  const fusionMultiplier = budgets.planners > 0 ? 1.5 : 1;
+  const costUnits = Math.ceil(budgets.agents * verifyRounds * sites * fusionMultiplier);
+  const breakdown = `tier=${tier} agents=${budgets.agents} verifyRounds=${verifyRounds} sites=${sites} fusion\xD7${fusionMultiplier}`;
+  return {
+    costUnits,
+    breakdown,
+    exceedsCeiling: costUnits > COST_CEILING
+  };
+}
+function decideOverCeiling(estimate, tier) {
+  if (!estimate.exceedsCeiling) return { action: "ok" };
+  if (tier === "light") return { action: "halt" };
+  const idx = TIER_LADDER.indexOf(tier);
+  const suggestedTier = idx > 0 ? TIER_LADDER[idx - 1] : "light";
+  return { action: "lower-tier", suggestedTier };
+}
+function frontierExhausted(state) {
+  const noUnblocked = (state.openUnblockedClaims ?? 0) === 0;
+  const noOpenPrs = (state.openInflightPrs ?? 0) === 0;
+  const frontierEmpty = state.nextFrontierEmpty ?? false;
+  const noUnresolvedParked = !(state.parkedSitesUnresolved ?? false);
+  return frontierEmpty && noUnblocked && noOpenPrs && noUnresolvedParked;
+}
+function campaignIterationCapExceeded(state) {
+  const cap = state.iterationCapOverride ?? CAMPAIGN_ITERATION_CAP;
+  return (state.orientCount ?? 0) >= cap;
+}
+function evaluateBuildFrontier(state) {
+  const iterationCap = state.iterationCapOverride ?? CAMPAIGN_ITERATION_CAP;
+  const exhausted = frontierExhausted(state);
+  const capHit = campaignIterationCapExceeded(state);
+  if (exhausted) {
+    return { frontierExhausted: true, iterationCapExceeded: capHit, iterationCap, recommend: "halt", haltReason: "frontier-exhausted" };
+  }
+  if (capHit) {
+    return { frontierExhausted: false, iterationCapExceeded: true, iterationCap, recommend: "halt", haltReason: "iteration-cap" };
+  }
+  return { frontierExhausted: false, iterationCapExceeded: false, iterationCap, recommend: "continue" };
+}
+
+// src/grind-policy.ts
+function isExplicitUltraYolo(input) {
+  return Boolean(input.ultra);
+}
+function getUltraCaps(input) {
+  if (isExplicitUltraYolo(input)) return { verifyRounds: 8, ciFixRounds: 5 };
+  return { verifyRounds: 5, ciFixRounds: 3 };
+}
+var GRIND_LENS_COUNT = 5;
+var GRIND_COST_CEILING = 200;
+var MIN_STABLE_CLEAN_ROUNDS = 2;
+function estimateGrindWorstCaseCost(opts) {
+  const caps = getUltraCaps(opts.input);
+  const lenses = opts.lensCount ?? GRIND_LENS_COUNT;
+  const models = opts.modelCount ?? (isExplicitUltraYolo(opts.input) || opts.input.autoUltra ? 3 : 2);
+  const verifyCost = caps.verifyRounds * lenses * models;
+  const synthesisCost = caps.verifyRounds;
+  const ciFixCost = opts.includeCiFix ? caps.ciFixRounds * 2 : 0;
+  const perPass = verifyCost + synthesisCost + ciFixCost;
+  const costUnits = perPass * MIN_STABLE_CLEAN_ROUNDS;
+  const breakdown = `verifyRounds=${caps.verifyRounds} lenses=${lenses} models=${models} synthesis=${synthesisCost} ciFix=${ciFixCost} stableRounds=${MIN_STABLE_CLEAN_ROUNDS}`;
+  return {
+    costUnits,
+    breakdown,
+    exceedsCeiling: costUnits > GRIND_COST_CEILING
+  };
+}
 
 // src/gc.ts
 var DEFERRED_SWEEP_COMMAND = "mmi-cli gc --apply";
@@ -8626,7 +9127,7 @@ function buildMmiPluginCacheCleanupCheck(input) {
   };
 }
 var NESTED_PLUGIN_TREE_LABEL = "self-nested MMI plugin cache tree (#1126)";
-var NESTED_PLUGIN_TREE_FIX = "run `mmi-cli doctor` to surface the MAX_PATH-safe robocopy cleanup for a self-nested MMI plugin cache tree (#1126)";
+var NESTED_PLUGIN_TREE_FIX = "SessionStart and mmi-cli doctor auto-clear when possible; if this persists, run the MAX_PATH-safe robocopy cleanup for a self-nested MMI plugin cache tree (#1126)";
 function nestedPluginTreeCleanupCommand(paths, isWindows) {
   if (paths.length === 0) return "";
   if (isWindows) {
@@ -14695,6 +15196,61 @@ build.command("tier").description("Recommend an effort tier (light|standard|deep
     console.log(`reasoning: ${decision.budgets.reasoningEffort}`);
   }
 });
+build.command("estimate").description("Worst-case cost proxy (agent-call units) for a milestone run \u2014 not a dollar promise").option("--scope <s>", "trivial|narrow|normal|wide|architectural").option("--risk <r>", "low|medium|high|critical").option("--ambiguity <a>", "low|medium|high").option("--blast-radius <b>", "isolated|module|cross-module|product").option("--foundational", "touches shared seams").option("--explicit <t>", "force a tier: light|standard|deep|max").option("--sites <n>", "planned L1 site count", (v) => parseInt(v, 10)).option("--json", "output JSON").action((opts) => {
+  const signals = {
+    scope: opts.scope,
+    risk: opts.risk,
+    ambiguity: opts.ambiguity,
+    blastRadius: opts.blastRadius,
+    foundational: opts.foundational ?? void 0,
+    explicitTier: opts.explicit
+  };
+  const tierDecision = pickEffortTier(signals);
+  const estimate = estimateWorstCaseCost({
+    signals,
+    tier: tierDecision.tier,
+    plannedSiteCount: opts.sites
+  });
+  const overCeiling = decideOverCeiling(estimate, tierDecision.tier);
+  const payload = {
+    tier: tierDecision.tier,
+    estimate,
+    ceiling: COST_CEILING,
+    overCeiling,
+    iterationCap: CAMPAIGN_ITERATION_CAP,
+    verificationDepthRounds: VERIFICATION_DEPTH_ROUNDS
+  };
+  if (opts.json) console.log(JSON.stringify(payload, null, 2));
+  else {
+    console.log(`tier:       ${tierDecision.tier}`);
+    console.log(`estimate:   ${estimate.costUnits} agent-call units (proxy, not dollars)`);
+    console.log(`breakdown:  ${estimate.breakdown}`);
+    const ceilingMsg = estimate.exceedsCeiling ? `EXCEEDS \u2192 ${overCeiling.action}${overCeiling.suggestedTier ? ` (try ${overCeiling.suggestedTier})` : ""}` : "within";
+    console.log(`ceiling:    ${COST_CEILING} units \u2014 ${ceilingMsg}`);
+    console.log(`L0 cap:     ${CAMPAIGN_ITERATION_CAP} orients (Phase 0 may override)`);
+  }
+});
+build.command("frontier").description("Evaluate external frontier exhaustion + L0 iteration cap (Ralph Wiggum guard)").option("--next-frontier-empty", "in-hand North Star has no unblocked frontier").option("--open-claims <n>", "open unblocked board claims", (v) => parseInt(v, 10)).option("--open-prs <n>", "in-flight PRs for milestone", (v) => parseInt(v, 10)).option("--parked-unresolved", "parked sites still waiting on hard decisions").option("--orient-count <n>", "L0 orient count this run", (v) => parseInt(v, 10)).option("--iteration-cap <n>", "Phase 0 override for L0 cap", (v) => parseInt(v, 10)).option("--json-file <path>", "full BuildExternalState JSON").option("--json", "output JSON").action(async (opts) => {
+  let state = {
+    nextFrontierEmpty: opts.nextFrontierEmpty ?? void 0,
+    openUnblockedClaims: opts.openClaims,
+    openInflightPrs: opts.openPrs,
+    parkedSitesUnresolved: opts.parkedUnresolved ?? void 0,
+    orientCount: opts.orientCount,
+    iterationCapOverride: opts.iterationCap
+  };
+  if (opts.jsonFile) {
+    const raw = await (0, import_promises5.readFile)(opts.jsonFile, "utf8");
+    state = { ...state, ...JSON.parse(raw) };
+  }
+  const result = evaluateBuildFrontier(state);
+  if (opts.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`frontierExhausted:   ${result.frontierExhausted}`);
+    console.log(`iterationCapExceeded: ${result.iterationCapExceeded} (cap ${result.iterationCap})`);
+    console.log(`recommend:           ${result.recommend}${result.haltReason ? ` (${result.haltReason})` : ""}`);
+  }
+});
 build.command("plan").description("Partition a set of issue refs into sites + waves (parallel/serialize/batch) for milestone construction").argument("[issues...]", "issue refs like owner/repo#N or #N").option("--json", "output JSON").action((issues, opts) => {
   const plan2 = {
     waves: issues.length > 0 ? [{ wave: 0, mode: "parallel", issues }] : [],
@@ -14706,6 +15262,26 @@ build.command("plan").description("Partition a set of issue refs into sites + wa
     for (const w of plan2.waves) console.log(`wave ${w.wave} (${w.mode}): ${w.issues.join(" ")}`);
   }
 });
+var grindCmd = program2.command("grind").description("Grind skill helpers \u2014 routing and cost proxies");
+grindCmd.command("estimate").description("Worst-case cost proxy (agent-call units) for one grind \u2014 not a dollar promise").option("--class <c>", "bug|feature|research|task|security-critical", "feature").option("--ultra", "explicit --ultra YOLO").option("--auto-ultra", "auto-ultra verify uplift (3 models)").option("--auto", "include CI-fix rounds").option("--models <n>", "panel model count", (v) => parseInt(v, 10)).option("--json", "output JSON").action((opts) => {
+  const input = {
+    grindClass: opts.class ?? "feature",
+    ultra: opts.ultra ?? void 0,
+    autoUltra: opts.autoUltra ?? void 0
+  };
+  const estimate = estimateGrindWorstCaseCost({
+    input,
+    modelCount: opts.models,
+    includeCiFix: opts.auto ?? false
+  });
+  const payload = { estimate, ceiling: GRIND_COST_CEILING, input };
+  if (opts.json) console.log(JSON.stringify(payload, null, 2));
+  else {
+    console.log(`estimate:   ${estimate.costUnits} agent-call units (proxy, not dollars)`);
+    console.log(`breakdown:  ${estimate.breakdown}`);
+    console.log(`ceiling:    ${GRIND_COST_CEILING} units \u2014 ${estimate.exceedsCeiling ? "EXCEEDS \u2192 ask human (cap/stuck path)" : "within"}`);
+  }
+});
 program2.command("skill-lesson").description("file a skill-lesson on the Hub board (GitHub auth, dedups open lessons) and print {number,url} JSON").requiredOption("--skill <name>", `which skill misfired (${SKILL_NAMES.join(" | ")})`).option("--title <title>", "one-line summary of what misfired").option("--title-file <path|->", "read the one-line summary from a UTF-8 file, or from stdin with -").option("--body <body>", "lesson body: what misfired, the evidence, and the proposed amendment (markdown)").option("--body-file <path|->", "read the lesson body from a UTF-8 file, or from stdin with -").option("--priority <priority>", "urgent | high | medium | low (board Priority field when configured)", "medium").option("--repo <owner/repo>", `target repo (defaults to the org Hub: ${HUB_REPO})`).option("--force", "file a new issue even when an open lesson looks like a duplicate").option("--json", "machine-readable output (already the default \u2014 skill-lesson always prints JSON)").action(async (o) => {
   const targetRepo2 = o.repo ?? HUB_REPO;
   const sourceRepo = await resolveRepo(void 0);
@@ -15857,6 +16433,46 @@ function quarantinePluginCacheDirs(plan2) {
   }
   return moved;
 }
+async function robocopyMirrorEmpty(emptyDir, target) {
+  try {
+    await execFileP2("robocopy", [emptyDir, target, "/MIR", "/NJH", "/NJS", "/NFL", "/NDL"], { timeout: CLAUDE_PLUGIN_TIMEOUT_MS });
+  } catch (e) {
+    const code = e.code;
+    if (typeof code === "number" && code <= 7) return;
+    throw e;
+  }
+}
+async function clearNestedPluginTreeDir(targetPath) {
+  try {
+    if (!(0, import_node_fs15.existsSync)(targetPath)) return true;
+    if (isWin) {
+      const emptyDir = (0, import_node_path14.join)((0, import_node_os5.tmpdir)(), `mmi-empty-${Date.now()}`);
+      (0, import_node_fs15.mkdirSync)(emptyDir, { recursive: true });
+      try {
+        await robocopyMirrorEmpty(emptyDir, targetPath);
+        (0, import_node_fs15.rmSync)(targetPath, { recursive: true, force: true });
+      } finally {
+        try {
+          (0, import_node_fs15.rmSync)(emptyDir, { recursive: true, force: true });
+        } catch {
+        }
+      }
+      return !(0, import_node_fs15.existsSync)(targetPath);
+    }
+    (0, import_node_fs15.rmSync)(targetPath, { recursive: true, force: true });
+    return !(0, import_node_fs15.existsSync)(targetPath);
+  } catch {
+    return false;
+  }
+}
+async function applyNestedPluginTreeCleanup(paths, log) {
+  if (paths.length === 0) return false;
+  log(`  \u21BB clearing ${paths.length} self-nested MMI plugin cache tree(s) (#1126)\u2026`);
+  for (const path2 of paths) {
+    if (!await clearNestedPluginTreeDir(path2)) return false;
+  }
+  return true;
+}
 var gitignorePath = () => (0, import_node_path14.join)(process.cwd(), ".gitignore");
 function readTextFile(path2) {
   try {
@@ -16019,7 +16635,7 @@ async function runDoctor(opts, io = consoleIo) {
     releasedVersion,
     surface
   });
-  if (!installedVersionCheck.ok && repairFull) {
+  if (!installedVersionCheck.ok && (repairFull || repairLocal)) {
     const claudeStale = installedVersionCheck.staleSurfaces?.some((s) => s.surface === "claude") ?? false;
     if (claudeStale && await applyClaudePluginHeal(surface, (m) => io.err(m))) {
       const healed = buildInstalledPluginVersionCheck({
@@ -16060,13 +16676,33 @@ async function runDoctor(opts, io = consoleIo) {
     };
   }
   checks.push(cacheCleanupCheck);
-  checks.push(
-    buildNestedPluginTreeCheck({
-      isOrgRepo: Boolean(cfg.sagaApiUrl),
-      isWindows: isWin,
-      entries: nestedPluginTreeSnapshot()
-    })
-  );
+  let nestedPluginTreeCheck = buildNestedPluginTreeCheck({
+    isOrgRepo: Boolean(cfg.sagaApiUrl),
+    isWindows: isWin,
+    entries: nestedPluginTreeSnapshot()
+  });
+  if (!nestedPluginTreeCheck.ok && nestedPluginTreeCheck.nested?.length && repairLocal) {
+    const nestedPaths = nestedPluginTreeCheck.nested.map((n) => n.path);
+    if (await applyNestedPluginTreeCleanup(nestedPaths, (m) => io.err(m))) {
+      nestedPluginTreeCheck = buildNestedPluginTreeCheck({
+        isOrgRepo: Boolean(cfg.sagaApiUrl),
+        isWindows: isWin,
+        entries: nestedPluginTreeSnapshot()
+      });
+      if (nestedPluginTreeCheck.ok) {
+        io.err(`  \u21BB cleared self-nested MMI plugin cache tree(s) \u2014 reinstalling plugin\u2026`);
+      }
+      if (await applyClaudePluginHeal(surface, (m) => io.err(m))) {
+        io.err(`  \u21BB reinstalled MMI plugin after nested-cache cleanup \u2014 ${reloadAction(surface)} to load MMI commands`);
+        nestedPluginTreeCheck = buildNestedPluginTreeCheck({
+          isOrgRepo: Boolean(cfg.sagaApiUrl),
+          isWindows: isWin,
+          entries: nestedPluginTreeSnapshot()
+        });
+      }
+    }
+  }
+  checks.push(nestedPluginTreeCheck);
   const cursorCacheRoot = cursorPluginCacheRoot();
   let cursorPins = cursorPluginCachePinSnapshots() ?? [];
   let cursorPluginCheck = buildCursorPluginInstallCheck({

package/dist/saga.cjs

@@ -3900,6 +3900,309 @@ function formatCaptureFailure(status, message) {
   return `saga: HTTP ${status}`;
 }
 
+// src/saga-snapshot.ts
+var GS_OPEN = "gs-open:";
+var GS_RESOLVED = "gs-resolved:";
+var GS_CEILING = "gs-ceiling:";
+var BS_DONE = "bs-done:";
+var BS_PROGRESS = "bs-progress:";
+var BS_BLOCKED = "bs-blocked:";
+var BS_TIER = "bs-tier:";
+var BS_CEILING = "bs-ceiling:";
+var BS_HALT = "bs-halt:";
+var GRIND_PREFIX = /^grind\s+/i;
+var META_ACTION_SEP = " | ";
+var LEGACY_BLOCKER_OPEN = /^blocker:(.+)$/i;
+var LEGACY_BLOCKER_RESOLVED = /^resolved:(.+)$/i;
+var LEGACY_CEILING = /^ceiling:(.+)$/i;
+var LEGACY_BUILD_DONE = /^done:(.+)$/i;
+var LEGACY_BUILD_PROGRESS = /^progress:(.+)$/i;
+var LEGACY_BUILD_BLOCKED = /^blocked:([^|]+)\|([^|]+)(?:\|(.+))?$/i;
+var LEGACY_BUILD_TIER = /^tier:([^|]+)\|([^|]+)(?:\|(.+))?$/i;
+var LEGACY_BUILD_CEILING = /^ceiling:([^|]+)\|(.+)$/i;
+var LEGACY_BUILD_HALT = /^halt:(.+)$/i;
+function isGrindSnapshotItem(text) {
+  return text.startsWith(GS_OPEN) || text.startsWith(GS_RESOLVED) || text.startsWith(GS_CEILING) || LEGACY_BLOCKER_OPEN.test(text) || LEGACY_BLOCKER_RESOLVED.test(text) || LEGACY_CEILING.test(text);
+}
+function isBuildSnapshotItem(text) {
+  return text.startsWith(BS_DONE) || text.startsWith(BS_PROGRESS) || text.startsWith(BS_BLOCKED) || text.startsWith(BS_TIER) || text.startsWith(BS_CEILING) || text.startsWith(BS_HALT) || LEGACY_BUILD_DONE.test(text) || LEGACY_BUILD_PROGRESS.test(text) || LEGACY_BUILD_BLOCKED.test(text) || LEGACY_BUILD_TIER.test(text) || LEGACY_BUILD_CEILING.test(text) || LEGACY_BUILD_HALT.test(text);
+}
+function snapshotClearIndices(kind, head) {
+  const pred = kind === "grind" ? isGrindSnapshotItem : isBuildSnapshotItem;
+  return (head.queued ?? []).map((item, index) => ({ item, index })).filter(({ item }) => !item.done && pred(item.text)).map(({ index }) => index);
+}
+function parseGrindNext(next) {
+  if (!next?.trim()) return {};
+  const raw = next.replace(GRIND_PREFIX, "").trim();
+  const pipe = raw.indexOf(META_ACTION_SEP);
+  const meta = pipe >= 0 ? raw.slice(0, pipe).trim() : raw;
+  const nextAction = pipe >= 0 ? raw.slice(pipe + META_ACTION_SEP.length).trim() : void 0;
+  const out = { nextAction };
+  for (const part of meta.split(/\s+/)) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const k = part.slice(0, eq);
+    const v = part.slice(eq + 1);
+    if (k === "class") out.class = v;
+    else if (k === "routing") out.routing = v;
+    else if (k === "ultra") out.ultra = v;
+    else if (k === "phase") out.phase = v;
+    else if (k === "verify") {
+      const [r, c] = v.split("/");
+      const rn = Number(r);
+      const cn = Number(c);
+      if (Number.isFinite(rn)) out.verifyRound = rn;
+      if (Number.isFinite(cn)) out.verifyCap = cn;
+    } else if (k === "resolved" && v) {
+      out.resolvedBlockerIds = v.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+  }
+  return out;
+}
+function formatGrindNext(s) {
+  const parts = ["grind"];
+  if (s.class) parts.push(`class=${s.class}`);
+  if (s.routing) parts.push(`routing=${s.routing}`);
+  if (s.ultra) parts.push(`ultra=${s.ultra}`);
+  if (s.phase) parts.push(`phase=${s.phase}`);
+  if (Number.isFinite(s.verifyRound) && Number.isFinite(s.verifyCap)) parts.push(`verify=${s.verifyRound}/${s.verifyCap}`);
+  if (s.resolvedBlockerIds.length) parts.push(`resolved=${s.resolvedBlockerIds.join(",")}`);
+  const meta = parts.join(" ");
+  return s.nextAction ? `${meta}${META_ACTION_SEP}${s.nextAction}` : meta;
+}
+function parseGrindQueueItem(item, open, resolved, ceiling) {
+  if (item.text.startsWith(GS_OPEN) && !item.done) open.push(item.text.slice(GS_OPEN.length).trim());
+  else if (item.text.startsWith(GS_RESOLVED) && !item.done) resolved.push(item.text.slice(GS_RESOLVED.length).trim());
+  else if (item.text.startsWith(GS_CEILING) && !item.done) ceiling.value = item.text.slice(GS_CEILING.length).trim();
+  else {
+    const legacyOpen = item.text.match(LEGACY_BLOCKER_OPEN);
+    if (legacyOpen && !item.done) open.push(legacyOpen[1].trim());
+    const legacyResolved = item.text.match(LEGACY_BLOCKER_RESOLVED);
+    if (legacyResolved && item.done) resolved.push(legacyResolved[1].trim());
+    const legacyCeil = item.text.match(LEGACY_CEILING);
+    if (legacyCeil && !item.done) ceiling.value = legacyCeil[1].trim();
+  }
+}
+function parseGrindSnapshot(head) {
+  const fromNext = parseGrindNext(head.next);
+  const openBlockerIds = [];
+  const resolvedFromQueue = [];
+  const ceiling = { value: void 0 };
+  for (const item of head.queued ?? []) {
+    parseGrindQueueItem(item, openBlockerIds, resolvedFromQueue, ceiling);
+  }
+  const resolvedBlockerIds = [.../* @__PURE__ */ new Set([...resolvedFromQueue, ...fromNext.resolvedBlockerIds ?? []])];
+  const { resolvedBlockerIds: _drop, ...restNext } = fromNext;
+  return {
+    kind: "grind",
+    criteria: head.anchor?.intent,
+    openBlockerIds,
+    resolvedBlockerIds,
+    verificationCeiling: ceiling.value,
+    ...restNext
+  };
+}
+function parseBuildSnapshot(head) {
+  const doneLastTurn = [];
+  const inProgress = [];
+  const blocked = [];
+  const tierLedger = [];
+  const verificationCeiling = [];
+  let haltReason;
+  for (const item of head.queued ?? []) {
+    if (item.text.startsWith(BS_DONE) && !item.done) {
+      doneLastTurn.push(item.text.slice(BS_DONE.length).trim());
+      continue;
+    }
+    if (item.text.startsWith(BS_PROGRESS) && !item.done) {
+      inProgress.push(item.text.slice(BS_PROGRESS.length).trim());
+      continue;
+    }
+    if (item.text.startsWith(BS_BLOCKED) && !item.done) {
+      const body = item.text.slice(BS_BLOCKED.length);
+      const [site, decision, issue] = body.split("|");
+      blocked.push({ site: site?.trim() ?? "", decision: decision?.trim() ?? "", issue: issue?.trim() });
+      continue;
+    }
+    if (item.text.startsWith(BS_TIER) && !item.done) {
+      const body = item.text.slice(BS_TIER.length);
+      const [site, tier2, signals] = body.split("|");
+      tierLedger.push({ site: site?.trim() ?? "", tier: tier2?.trim() ?? "", signals: signals?.trim() });
+      continue;
+    }
+    if (item.text.startsWith(BS_CEILING) && !item.done) {
+      const body = item.text.slice(BS_CEILING.length);
+      const [site, rung] = body.split("|");
+      verificationCeiling.push({ site: site?.trim() ?? "", rung: rung?.trim() ?? "" });
+      continue;
+    }
+    if (item.text.startsWith(BS_HALT) && !item.done) {
+      haltReason = item.text.slice(BS_HALT.length).trim();
+      continue;
+    }
+    if (item.done) {
+      const d = item.text.match(LEGACY_BUILD_DONE);
+      if (d) doneLastTurn.push(d[1].trim());
+      continue;
+    }
+    const prog = item.text.match(LEGACY_BUILD_PROGRESS);
+    if (prog) {
+      inProgress.push(prog[1].trim());
+      continue;
+    }
+    const blk = item.text.match(LEGACY_BUILD_BLOCKED);
+    if (blk) {
+      blocked.push({ site: blk[1].trim(), decision: blk[2].trim(), issue: blk[3]?.trim() });
+      continue;
+    }
+    const tier = item.text.match(LEGACY_BUILD_TIER);
+    if (tier) {
+      tierLedger.push({ site: tier[1].trim(), tier: tier[2].trim(), signals: tier[3]?.trim() });
+      continue;
+    }
+    const ceil = item.text.match(LEGACY_BUILD_CEILING);
+    if (ceil) {
+      verificationCeiling.push({ site: ceil[1].trim(), rung: ceil[2].trim() });
+      continue;
+    }
+    const halt = item.text.match(LEGACY_BUILD_HALT);
+    if (halt) haltReason = halt[1].trim();
+  }
+  const nextFrontier = [];
+  if (head.next?.trim()) {
+    for (const line of head.next.split(";").map((s) => s.trim()).filter(Boolean)) {
+      nextFrontier.push(line);
+    }
+  }
+  return {
+    kind: "build",
+    milestone: head.anchor?.intent,
+    northStarSlug: head.anchor?.slug,
+    doneLastTurn,
+    inProgress,
+    blocked,
+    nextFrontier,
+    tierLedger,
+    verificationCeiling,
+    haltReason
+  };
+}
+function parseSnapshot(kind, head) {
+  return kind === "grind" ? parseGrindSnapshot(head) : parseBuildSnapshot(head);
+}
+function strOrU(v) {
+  return typeof v === "string" && v.length ? v : void 0;
+}
+function numOrU(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function normalizeSnapshot(kind, raw) {
+  if (!raw || typeof raw !== "object") throw new Error("snapshot JSON must be an object");
+  const o = raw;
+  if (o.kind !== kind) throw new Error(`snapshot kind ${JSON.stringify(o.kind)} does not match --kind ${kind}`);
+  if (kind === "grind") {
+    return {
+      kind: "grind",
+      class: strOrU(o.class),
+      routing: strOrU(o.routing),
+      ultra: strOrU(o.ultra),
+      criteria: strOrU(o.criteria),
+      phase: strOrU(o.phase),
+      verifyRound: numOrU(o.verifyRound),
+      verifyCap: numOrU(o.verifyCap),
+      openBlockerIds: asStringArray(o.openBlockerIds),
+      resolvedBlockerIds: asStringArray(o.resolvedBlockerIds),
+      verificationCeiling: strOrU(o.verificationCeiling),
+      nextAction: strOrU(o.nextAction)
+    };
+  }
+  const blocked = Array.isArray(o.blocked) ? o.blocked.filter((b) => !!b && typeof b === "object").map((b) => ({ site: strOrU(b.site) ?? "", decision: strOrU(b.decision) ?? "", issue: strOrU(b.issue) })) : [];
+  const tierLedger = Array.isArray(o.tierLedger) ? o.tierLedger.filter((t) => !!t && typeof t === "object").map((t) => ({ site: strOrU(t.site) ?? "", tier: strOrU(t.tier) ?? "", signals: strOrU(t.signals) })) : [];
+  const verificationCeiling = Array.isArray(o.verificationCeiling) ? o.verificationCeiling.filter((v) => !!v && typeof v === "object").map((v) => ({ site: strOrU(v.site) ?? "", rung: strOrU(v.rung) ?? "" })) : [];
+  return {
+    kind: "build",
+    milestone: strOrU(o.milestone),
+    northStarSlug: strOrU(o.northStarSlug),
+    doneLastTurn: asStringArray(o.doneLastTurn),
+    inProgress: asStringArray(o.inProgress),
+    blocked,
+    nextFrontier: asStringArray(o.nextFrontier),
+    tierLedger,
+    verificationCeiling,
+    haltReason: strOrU(o.haltReason)
+  };
+}
+function planGrindSnapshotWrite(s, summary = "grind snapshot refresh") {
+  const queueOps = [];
+  for (const id of s.openBlockerIds) queueOps.push({ text: `${GS_OPEN}${id}` });
+  for (const id of s.resolvedBlockerIds) queueOps.push({ text: `${GS_RESOLVED}${id}` });
+  if (s.verificationCeiling) queueOps.push({ text: `${GS_CEILING}${s.verificationCeiling}` });
+  return {
+    summary,
+    next: formatGrindNext(s),
+    anchor: s.criteria,
+    queueOps,
+    clearIndices: []
+  };
+}
+function planBuildSnapshotWrite(s, summary = "build snapshot refresh") {
+  const queueOps = [];
+  for (const site of s.doneLastTurn) queueOps.push({ text: `${BS_DONE}${site}` });
+  for (const site of s.inProgress) queueOps.push({ text: `${BS_PROGRESS}${site}` });
+  for (const b of s.blocked) {
+    queueOps.push({ text: `${BS_BLOCKED}${b.site}|${b.decision}${b.issue ? `|${b.issue}` : ""}` });
+  }
+  for (const t of s.tierLedger) {
+    queueOps.push({ text: `${BS_TIER}${t.site}|${t.tier}${t.signals ? `|${t.signals}` : ""}` });
+  }
+  for (const v of s.verificationCeiling) queueOps.push({ text: `${BS_CEILING}${v.site}|${v.rung}` });
+  if (s.haltReason) queueOps.push({ text: `${BS_HALT}${s.haltReason}` });
+  return {
+    summary,
+    next: s.nextFrontier.length ? s.nextFrontier.join("; ") : void 0,
+    anchor: s.milestone,
+    anchorSlug: s.northStarSlug,
+    queueOps,
+    clearIndices: []
+  };
+}
+function planSnapshotWrite(snapshot, head, summary) {
+  const plan = snapshot.kind === "grind" ? planGrindSnapshotWrite(snapshot, summary) : planBuildSnapshotWrite(snapshot, summary);
+  plan.clearIndices = snapshotClearIndices(snapshot.kind, head);
+  return plan;
+}
+function formatSnapshotHuman(snapshot) {
+  if (snapshot.kind === "grind") {
+    const lines2 = [
+      `kind: grind`,
+      snapshot.class ? `class: ${snapshot.class}` : "",
+      snapshot.routing ? `routing: ${snapshot.routing}` : "",
+      snapshot.ultra ? `ultra: ${snapshot.ultra}` : "",
+      snapshot.criteria ? `criteria: ${snapshot.criteria}` : "",
+      snapshot.phase ? `phase: ${snapshot.phase}` : "",
+      snapshot.verifyRound != null ? `verify: ${snapshot.verifyRound}/${snapshot.verifyCap ?? "?"}` : "",
+      snapshot.openBlockerIds.length ? `open blockers: ${snapshot.openBlockerIds.join(", ")}` : "open blockers: (none)",
+      snapshot.resolvedBlockerIds.length ? `resolved: ${snapshot.resolvedBlockerIds.join(", ")}` : "",
+      snapshot.verificationCeiling ? `ceiling: ${snapshot.verificationCeiling}` : "",
+      snapshot.nextAction ? `next: ${snapshot.nextAction}` : ""
+    ].filter(Boolean);
+    return lines2.join("\n");
+  }
+  const lines = [
+    `kind: build`,
+    snapshot.milestone ? `milestone: ${snapshot.milestone}` : "",
+    snapshot.northStarSlug ? `north star: ${snapshot.northStarSlug}` : "",
+    snapshot.doneLastTurn.length ? `done: ${snapshot.doneLastTurn.join(", ")}` : "",
+    snapshot.inProgress.length ? `in progress: ${snapshot.inProgress.join(", ")}` : "",
+    snapshot.nextFrontier.length ? `next frontier: ${snapshot.nextFrontier.join("; ")}` : "",
+    snapshot.haltReason ? `halt: ${snapshot.haltReason}` : ""
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+
 // src/hub-auth.ts
 var import_node_crypto = require("node:crypto");
 var import_node_fs5 = require("node:fs");
@@ -4321,6 +4624,60 @@ async function runSagaHealth(o, io = consoleIo) {
   if (report.warnings.length) io.log(report.warnings.map((w) => ` - ${w}`).join("\n"));
   if (report.pendingNotes > 0) io.log(` - ${report.pendingNotes} note(s) queued locally \u2014 \`mmi-cli saga flush\` to roll forward`);
 }
+async function fetchSagaHead(io = consoleIo) {
+  const cfg = await loadConfig();
+  if (!cfg.sagaApiUrl) {
+    io.err("saga snapshot: Hub API URL not configured");
+    return null;
+  }
+  try {
+    const key = await sagaKey(cfg);
+    const qs = new URLSearchParams(key).toString();
+    const res = await fetch(`${cfg.sagaApiUrl}/saga/state?${qs}`, { headers: await hubHeaders(), signal: AbortSignal.timeout(8e3) });
+    if (!res.ok) {
+      io.err(`saga snapshot: HTTP ${res.status}`);
+      return null;
+    }
+    const state = await res.json();
+    return state.head ?? {};
+  } catch (e) {
+    io.err(`saga snapshot: ${e.message}`);
+    return null;
+  }
+}
+async function postSnapshotNotes(plan, anchorForce) {
+  const [sha, key] = await Promise.all([gitOut(["rev-parse", "--short", "HEAD"]), sagaKey(await loadConfig())]);
+  const evidence = { sha: sha || void 0, branch: key.branch };
+  for (const idx of [...plan.clearIndices].sort((a, b) => b - a)) {
+    const cap = buildNoteCapture("snapshot retire", { queueDone: String(idx) }, (0, import_node_crypto3.randomUUID)(), evidence);
+    await postCapture(cap);
+  }
+  const primary = buildNoteCapture(plan.summary, {
+    next: plan.next,
+    anchor: plan.anchor,
+    anchorSlug: plan.anchorSlug,
+    anchorForce
+  }, (0, import_node_crypto3.randomUUID)(), evidence);
+  await postCapture(primary);
+  for (const op of plan.queueOps) {
+    const cap = buildNoteCapture("snapshot checklist", { queueAdd: op.text }, (0, import_node_crypto3.randomUUID)(), evidence);
+    await postCapture(cap);
+  }
+}
+async function runSagaSnapshotShow(opts, io = consoleIo) {
+  const head = await fetchSagaHead(io);
+  if (!head) return;
+  const snapshot = parseSnapshot(opts.kind, head);
+  if (opts.json) return io.log(JSON.stringify(snapshot, null, 2));
+  io.log(formatSnapshotHuman(snapshot));
+}
+async function runSagaSnapshotSet(snapshot, opts = {}, io = consoleIo) {
+  const head = await fetchSagaHead(io) ?? { queued: [] };
+  const plan = planSnapshotWrite(snapshot, head);
+  await postSnapshotNotes(plan, opts.anchorForce);
+  if (opts.json) return io.log(JSON.stringify({ ok: true, snapshot, retired: plan.clearIndices.length, queued: plan.queueOps.length + 1 }));
+  io.log(`saga snapshot: wrote ${snapshot.kind} snapshot (retired ${plan.clearIndices.length}, ${plan.queueOps.length + 1} capture(s))`);
+}
 function registerSagaCommands(program2) {
   const saga = program2.command("saga").description("per-session continuity");
   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-slug <slug>", "bind the anchor to a North Star plan slug (SSOT at plans/.../<slug>.md)").option("--anchor-force", "overwrite an existing anchor").option("--message-file <path|->", "read the summary from a UTF-8 file, or from stdin with - (avoids cmd.exe quoting)").action(async (summary, o) => {
@@ -4386,6 +4743,69 @@ function registerSagaCommands(program2) {
     console.log(`project=${key.project} branch=${key.branch} session=${key.sessionId} source=${source}`);
   });
   saga.command("health").option("--json", "machine-readable output").option("--banner", "one-line SessionStart banner; silent when healthy").option("--quiet", "suppress detail output").description("zero-write health check: auth, backend reachability, resolved key").action((o) => runSagaHealth(o));
+  const snapshot = saga.command("snapshot").description("structured grind/build resume snapshot over saga HEAD");
+  snapshot.command("show").description("read the structured resume snapshot from current saga HEAD").requiredOption("--kind <kind>", "grind | build").option("--json", "output JSON").action(async (o) => {
+    const kind = o.kind;
+    if (kind !== "grind" && kind !== "build") return fail("saga snapshot show: --kind must be grind or build");
+    await runSagaSnapshotShow({ kind, json: o.json });
+  });
+  snapshot.command("set").description("write a structured resume snapshot (maps to saga note HEAD primitives)").requiredOption("--kind <kind>", "grind | build").option("--json-file <path>", "full snapshot JSON (overrides field flags)").option("--anchor-force", "overwrite an existing anchor").option("--json", "output result JSON").option("--class <c>", "grind class").option("--routing <r>", "grind routing tier").option("--ultra <u>", "ultra mode").option("--criteria <text>", "grind criteria / frame").option("--phase <p>", "phase reached").option("--verify-round <n>", "verify round", (v) => parseInt(v, 10)).option("--verify-cap <n>", "verify cap", (v) => parseInt(v, 10)).option("--open-blocker <id>", "open blocker id (repeatable)", (v, prev) => [...prev, v], []).option("--resolved-blocker <id>", "resolved blocker id (repeatable)", (v, prev) => [...prev, v], []).option("--verification-ceiling <text>", "verification ceiling").option("--next-action <text>", "next action").option("--milestone <text>", "build milestone one-liner").option("--north-star-slug <slug>", "North Star slug").option("--done <site>", "done last turn site (repeatable)", (v, prev) => [...prev, v], []).option("--in-progress <site>", "in-progress site (repeatable)", (v, prev) => [...prev, v], []).option("--blocked <spec>", "site|decision|issue (repeatable)", (v, prev) => [...prev, v], []).option("--next-frontier <item>", "frontier item (repeatable)", (v, prev) => [...prev, v], []).option("--tier <spec>", "site|tier|signals (repeatable)", (v, prev) => [...prev, v], []).option("--site-ceiling <spec>", "site|rung (repeatable)", (v, prev) => [...prev, v], []).option("--halt-reason <text>", "halt reason").action(async (o) => {
+    const kind = o.kind;
+    if (kind !== "grind" && kind !== "build") return fail("saga snapshot set: --kind must be grind or build");
+    let snap;
+    if (o.jsonFile) {
+      const raw = await (0, import_promises2.readFile)(o.jsonFile, "utf8");
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (e) {
+        return fail(`saga snapshot set: invalid JSON in ${o.jsonFile}: ${e.message}`);
+      }
+      try {
+        snap = normalizeSnapshot(kind, parsed);
+      } catch (e) {
+        return fail(`saga snapshot set: ${e.message}`);
+      }
+    } else if (kind === "grind") {
+      snap = {
+        kind: "grind",
+        class: o.class,
+        routing: o.routing,
+        ultra: o.ultra,
+        criteria: o.criteria,
+        phase: o.phase,
+        verifyRound: o.verifyRound,
+        verifyCap: o.verifyCap,
+        openBlockerIds: o.openBlocker ?? [],
+        resolvedBlockerIds: o.resolvedBlocker ?? [],
+        verificationCeiling: o.verificationCeiling,
+        nextAction: o.nextAction
+      };
+    } else {
+      snap = {
+        kind: "build",
+        milestone: o.milestone,
+        northStarSlug: o.northStarSlug,
+        doneLastTurn: o.done ?? [],
+        inProgress: o.inProgress ?? [],
+        blocked: (o.blocked ?? []).map((spec) => {
+          const [site, decision, issue] = spec.split("|");
+          return { site: site ?? "", decision: decision ?? "", issue };
+        }),
+        nextFrontier: o.nextFrontier ?? [],
+        tierLedger: (o.tier ?? []).map((spec) => {
+          const [site, tier, signals] = spec.split("|");
+          return { site: site ?? "", tier: tier ?? "", signals };
+        }),
+        verificationCeiling: (o.siteCeiling ?? []).map((spec) => {
+          const [site, rung] = spec.split("|");
+          return { site: site ?? "", rung: rung ?? "" };
+        }),
+        haltReason: o.haltReason
+      };
+    }
+    await runSagaSnapshotSet(snap, { anchorForce: o.anchorForce, json: o.json });
+  });
 }
 
 // src/saga-boot.ts

package/package.json

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